Tools Reference

This guide documents the tools available in the AVCodex MCP Server, organized by category.

Jump to a category or use this table to find tools quickly:

Note: AVCodex agents are stored as "apps" in the underlying API. Tool names and parameters use app and app_id. They map to AVCodex agents.

Core CRUD operations for managing AVCodex agents.

list_apps#

List every agent accessible to the authenticated user.

Scope: apps:read

Example:

"List all my AVCodex agents"
"Show agents in workspace 42"

get_app#

Get detailed information about a specific agent.

Scope: apps:read

Example:

"Get details for agent 123"
"Show me the configuration of my Crestron support agent"

create_app#

Create a new agent in a workspace.

Scope: apps:write

Example:

"Create a Crestron tier-1 support agent called RoomMedic in workspace 5"
"Make a new agent named RFP Responder with a helpful estimating prompt"

update_app#

Update an existing agent's properties.

Scope: apps:write

Example:

"Rename agent 123 to 'Tier-1 Support v2'"
"Make my client-facing AV agent publicly listed"

delete_app#

Soft-delete an agent.

Scope: apps:write

Example:

"Delete agent 123"
"Remove the test agent I created"

chat_with_app#

Send a message to an agent and get a response. Useful for testing.

Scope: apps:read

Tip: Use this tool to test agents after making changes. It is faster than switching to the web UI.

Example:

"Test my Crestron agent with the question 'What does Cresnet error 87 mean?'"
"Send 'hello' to agent 123 to check if it's working"

search_apps#

Search agents by name or description within your organization.

Scope: apps:read

publish_app#

Publish the current agent configuration to make it live for consumers. Creates a version snapshot and deploys it.

Scope: apps:write

Returns: version_id, already_published flag, and the tag used.

list_app_versions#

List published version history for an agent.

Scope: apps:read

duplicate_app#

Create a copy of an existing agent with all its configuration, system prompt, and settings. Useful for spinning up a per-client agent from a template (one base "Crestron Tier-1" agent cloned for every managed-services client).

Scope: apps:write

restore_app_version#

Restore an agent's configuration to a previous version. Does not publish. Use publish_app afterward if needed.

Scope: apps:write

rollback_app_version#

Rollback an agent to a previously published version and immediately publish it. Combines restore and publish in one step.

Scope: apps:write

get_app_url#

Get the consumer-facing URL for an agent (custom domain, vanity subdomain, or default path). Also returns the embed widget snippet.

Scope: apps:read

Returns: consumer_url, default_url, has_custom_domain, and embed_snippet.

Manage agent settings, system prompts, and branding.

get_system_prompt#

Get the system prompt for an agent.

Scope: apps:read

update_system_prompt#

Update an agent's system prompt.

Scope: apps:write

Warning: Changes take effect immediately for new conversations. Use chat_with_app to test before deploying to users.

get_model#

Get the AI model configuration for an agent.

Scope: apps:read

update_model#

Change the AI model for an agent.

Scope: apps:write

get_settings#

Get detailed settings including RAG configuration.

Scope: apps:read

update_settings#

Update agent settings, capabilities, welcome messages, and suggested starters.

Scope: apps:write

update_branding#

Update visual branding for the agent.

Scope: apps:write

list_suggestions#

Get the suggested conversation starters shown to users on the chat interface.

Scope: apps:read

update_suggestions#

Set the suggested conversation starters shown to users. Pass an empty array to clear all suggestions.

Scope: apps:write

Example:

"Set the starter prompts for my support agent to: 'TSW touch panel is unresponsive', 'Cresnet device offline', 'Schedule a service call'"

Manage RAG (Retrieval-Augmented Generation) knowledge bases. Load Crestron module reference, Biamp Tesira spec PDFs, AS-built drawings, AMX programming guides, internal commissioning SOPs.

list_knowledge_sources#

List all knowledge sources for an agent.

Scope: knowledge:read

get_knowledge_source#

Get details about a specific knowledge source.

Scope: knowledge:read

add_url_source#

Add a URL as a knowledge source. Automatically detects YouTube, Instagram, TikTok, and regular web pages.

Scope: knowledge:write

Note: Smart Detection. YouTube URLs extract transcripts, social media extracts content, regular URLs are crawled. Useful for ingesting manufacturer training videos and a vendor's full doc site in one step.

Example:

"Add https://docs.biamp.com/tesira to my design agent and crawl 3 levels deep"
"Add this Crestron training video to my onboarding agent's knowledge base"

add_text_source#

Add raw text content as a knowledge source.

Scope: knowledge:write

Example:

"Add this commissioning checklist text to my deployment agent's knowledge base"

delete_knowledge_source#

Remove a knowledge source from an agent.

Scope: knowledge:write

refresh_knowledge_source#

Re-crawl or re-process a knowledge source to update its content. Useful when a manufacturer publishes a new firmware-release notes page.

Scope: knowledge:write

list_active_crawls#

List knowledge sources currently being processed or queued for an agent.

Scope: knowledge:read

Returns: Active processing jobs with job type, status, attempt counts, and the source name/URL being processed.

cancel_crawl#

Cancel all pending and in-progress processing jobs for a knowledge source.

Scope: knowledge:write

The source status is set to failed. Jobs already running on a worker may complete, but no new queued jobs will start.

add_document_source#

Upload one or more document files as knowledge sources. Files are provided as base64-encoded content. Drop in PDFs of Crestron module reference, Biamp DSP guides, Q-SYS Designer help exports, room CAD packages, AS-built docs.

Scope: knowledge:write

Supported formats: PDF, DOCX, TXT, MD, CSV, JSON, XLSX, XLS, and audio files (MP3, WAV, M4A, etc.).

Each file object requires fileName (with extension) and content (base64-encoded).

get_crawl_progress#

Get the processing progress for a knowledge source. Current status, chunk count, pages completed, and any error messages.

Scope: knowledge:read

link_knowledge_source#

Link a knowledge source from one agent to another, sharing its RAG data without duplicating it. Useful for sharing one master Crestron docs source across every client-specific support agent.

Scope: knowledge:write

unlink_knowledge_source#

Remove a linked knowledge source from an agent. Does not delete the original source.

Scope: knowledge:write

list_linked_knowledge_sources#

List knowledge sources linked to an agent from other agents (shared sources).

Scope: knowledge:read

Access usage data, conversations, and metrics.

get_app_analytics#

Get summary analytics for an agent: total sessions, messages, unique users, and date range stats.

Scope: analytics:read

Returns: Total sessions, messages, unique users, first and last session timestamps.

search_conversations#

Search conversations with filters.

Scope: analytics:read

Example:

"Find conversations about Cresnet timeouts in my support agent"
"Show recent conversations from the last week"

get_conversation#

Get a specific conversation with all messages.

Scope: analytics:read

get_top_queries#

Get the most common user queries.

Scope: analytics:read

get_model_usage#

Get LLM model usage breakdown (token counts by model) for an agent.

Scope: analytics:read

get_response_time_analytics#

Get response time statistics based on message timestamps.

Scope: analytics:read

Returns: Total responses, avg response ms, p50, p95.

get_user_engagement#

Get user engagement metrics: sessions per user, messages per session, return rate.

Scope: analytics:read

search_messages#

Search for specific text within messages across all conversations in an agent.

Scope: analytics:read

Returns matching messages with a 500-character content preview and session context.

search_documentation#

Full-text search within an agent's knowledge base (RAG chunks).

Scope: knowledge:read

Useful for checking what content is indexed before a chat, or debugging RAG retrieval issues. ("Did the Tesira firmware notes page actually get crawled?")

get_tag_analytics#

Get tag usage statistics for an agent over a time period.

Scope: analytics:read

Returns: Per-tag counts for total fires, active fires, removed fires, text-replaced count, avg similarity, and last fired timestamp.

get_file_analytics#

Get file upload statistics for an agent: upload counts and total storage by MIME type.

Scope: analytics:read

Returns: Breakdown for both chat session uploads and consumer brain files.

get_moderation_stats#

Get moderation statistics: how many conversations were frozen, had responses replaced, or triggered notifications.

Scope: analytics:read

Returns: Tag fire counts broken down by action type (freeze, static text, notification, webhook, manually removed) and affected session count.

get_popular_apps#

Get the most-used agents in your organization, ranked by session count and unique users.

Scope: analytics:read

export_conversations#

Export conversations as JSON for an agent within a date range.

Scope: analytics:read

Manage intent tags for message classification and automated responses.

list_tags#

List all tags for an agent.

Scope: apps:read

get_tag#

Get details for a specific tag, including utterances.

Scope: apps:read

create_tag#

Create a new intent tag.

Scope: apps:write

Action types:

• staticText: Replace the AI response with fixed text.
• freeze: Stop conversation flow.
• notification: Send webhook or email alert.

Example:

"Create a tag called 'truck-roll-needed' for my support agent with utterances like 'send a tech', 'come on site', 'we need someone in the room'"

update_tag#

Update an existing tag.

Scope: apps:write

delete_tag#

Delete a tag.

Scope: apps:write

list_tag_instances#

List messages that matched a specific tag.

Scope: analytics:read

remove_tag_instance#

Soft-delete a specific tag detection instance from a message. The instance is marked as removed rather than permanently deleted.

Scope: apps:write

generate_utterances#

Generate training utterances for a tag using AI. Utterances are example phrases that should trigger the tag. More utterances means better detection accuracy.

Scope: apps:write

Example:

"Generate 30 training utterances for a tag called 'projector lamp issue' for a higher-ed classroom support agent"

Create and run quality tests for your agents. Run an eval suite over a tier-1 Crestron support agent before pushing prompt changes to production.

list_evals#

List all evaluations for an agent.

Scope: apps:read

get_eval#

Get details for a specific evaluation.

Scope: apps:read

create_eval#

Create a new evaluation with test cases for an agent.

Scope: apps:write

Test case format:

{
  "input": "TSW-1070 is showing offline. What do I check first?",
  "expected_output": "Check the Cresnet bus power, verify the touch panel's IP via Toolbox, then check the control system's program for the device ID."
}

update_eval#

Update an existing evaluation's name, test cases, or method.

Scope: apps:write

delete_eval#

Delete an evaluation.

Scope: apps:write

run_eval#

Run an evaluation against the agent to score its responses on the test cases.

Scope: apps:write

list_eval_results#

List past evaluation runs.

Scope: apps:read

get_eval_result#

Get detailed results from a specific evaluation run.

Scope: apps:read

Manage API integrations for your agents. Open a service ticket in your PSA, query a control system processor, push a status update to a project tracker.

list_custom_actions#

List all custom actions for an agent.

Scope: actions:read

get_custom_action#

Get details for a specific custom action.

Scope: actions:read

create_custom_action#

Create a new API integration.

Scope: actions:write

Note: Custom actions have complex schemas. See the Custom Actions Guide for detailed examples.

update_custom_action#

Update an existing custom action.

Scope: actions:write

delete_custom_action#

Delete a custom action.

Scope: actions:write

test_custom_action#

Test a custom action by executing it with sample parameters.

Scope: actions:write

Connect external MCP servers to your agents.

list_mcp_integrations#

List all connected MCP servers for an agent.

Scope: actions:read

get_mcp_integration#

Get details about a connected MCP server.

Scope: actions:read

connect_mcp_server#

Connect an external MCP server to an agent.

Scope: actions:write

update_mcp_integration_tools#

Enable or disable the entire MCP integration, or toggle specific tools by name.

Scope: actions:write

disconnect_mcp_server#

Remove an MCP server connection.

Scope: actions:write

list_hosted_integrations#

List hosted integration providers connected to an agent (Google Drive, Gmail, Outlook, OneDrive, Slack, and others).

Scope: apps:read

Returns: For each integration: provider, label, is_active, account_email, and requires_consumer_auth.

Manage multi-channel deployments (Slack, WhatsApp, Email, Voice).

list_slack_deployments#

List Slack workspace connections.

Scope: apps:read

get_slack_deployment#

Get details about a Slack deployment.

Scope: apps:read

disconnect_slack_deployment#

Remove a Slack connection.

Scope: apps:write

get_whatsapp_deployment#

Get WhatsApp business configuration.

Scope: apps:read

get_voice_config#

Get voice agent configuration.

Scope: apps:read

update_voice_config#

Update voice agent settings.

Scope: apps:write

get_email_deployment#

Get email channel configuration.

Scope: apps:read

update_email_deployment#

Update email channel settings.

Scope: apps:write

get_discord_deployment#

Get the Discord bot integration status for an agent.

Scope: apps:read

Returns: connected, discord_app_id, is_active, and connection timestamp.

get_github_deployment#

Get the GitHub App integration status for an agent (auto-respond to issues and PRs).

Scope: apps:read

Returns: connected, account_login, auto_respond_issues, and installation details.

Manage end-users (consumers) of your agents. The end-users in this case might be your client's employees, your field techs, or anyone else hitting the agent.

list_consumers#

List consumers of an agent with search and filtering.

Scope: analytics:read

get_consumer#

Get details about a specific consumer including their session count.

Scope: analytics:read

update_consumer#

Update a consumer's credit balance or subscription status.

Scope: apps:write

get_user_memories#

Get the AI memories stored for a specific consumer. Facts and context the agent has learned across conversations (which rooms a tech typically services, the IT contact at a particular client site, the control system in place at each campus building).

Scope: analytics:read

Only active (non-superseded) memories are returned.

Manage workspaces and team members.

list_workspaces#

List all workspaces you have access to.

Scope: workspace:read

get_workspace#

Get details about a specific workspace.

Scope: workspace:read

list_workspace_members#

List members of a workspace.

Scope: workspace:read

create_workspace#

Create a new workspace in your organization.

Scope: workspace:write

Example:

"Create a new workspace called Service Operations"

View subscription and credit information.

get_subscription#

Get subscription details for an organization.

Scope: billing:read

get_credits#

Get credit balance and usage.

Scope: billing:read

get_usage#

Get LLM token usage and non-LLM usage events for the organization.

Scope: billing:read

get_usage_by_app#

Get token usage broken down by agent for the organization.

Scope: billing:read

Returns: Per-agent totals for call_count, total_input_tokens, and total_output_tokens.

get_capabilities#

Get a boolean map of all feature capabilities for the organization. What features are available based on tier, add-ons, and feature flags.

Scope: billing:read

AI-assisted tools for improving prompts and selecting models.

list_available_models#

List all AI models available for use.

Scope: apps:read

generate_system_prompt#

Generate a new system prompt from a description.

Scope: apps:write

improve_system_prompt#

Use AI to analyze and improve an existing system prompt.

Scope: apps:write

recommend_model#

Get AI-powered model recommendations for your use case.

Scope: apps:read

generate_suggestions#

Generate conversation starter suggestions for an agent based on its system prompt. These are the suggested messages shown to users to begin a conversation.

Scope: apps:read

Example:

"Generate 6 starter suggestions for my Q-SYS support agent"

Manage reusable action bundles that can be linked to multiple agents.

list_action_collections#

List action collections owned by you or shared within your organization.

Scope: actions:read

get_action_collection#

Get details for a specific action collection.

Scope: actions:read

create_action_collection#

Create a new action collection.

Scope: actions:write

update_action_collection#

Update an action collection's name or description.

Scope: actions:write

delete_action_collection#

Delete an action collection. Also removes it from any linked agents.

Scope: actions:write

link_collection_to_app#

Link an action collection to an agent, making its actions available.

Scope: actions:write

unlink_collection_from_app#

Remove an action collection from an agent.

Scope: actions:write

list_linked_collections#

List all action collections linked to a specific agent.

Scope: actions:read

update_collection_sharing#

Update the sharing scope of an action collection.

Scope: actions:write

• PRIVATE. Only you can see it.
• WORKSPACE. Anyone in your workspace can discover and link it.
• PUBLIC. Visible in the marketplace.

import_collection_tools#

Import tools from an action collection into an agent as standalone custom actions. Unlike link_collection_to_app, imported tools are independent copies you can modify freely without affecting the source collection.

Scope: actions:write

Returns: Count of imported tools and any that were skipped due to slug conflicts.

Manage agent variables (key-value configuration used by custom actions). Useful for per-client API keys, control system IPs, headend hostnames.

list_app_variables#

List all variables for an agent.

Scope: apps:read

get_app_variable#

Get details for a specific agent variable.

Scope: apps:read

create_app_variable#

Create a new agent variable.

Scope: apps:write

update_app_variable#

Update an agent variable's value, label, or description.

Scope: apps:write

delete_app_variable#

Delete an agent variable.

Scope: apps:write

Configure and monitor proactive messaging (heartbeat). Your agent reaching out to consumers on a schedule. Ideal for monthly health checks across a managed-services portfolio or weekly status pings to project stakeholders.

get_heartbeat_config#

Get the heartbeat configuration for an agent.

Scope: apps:read

Returns: enabled, every, prompt, checklist, targets, and model.

update_heartbeat_config#

Update heartbeat configuration. Set the interval, prompt, delivery channels, and model.

Scope: apps:write

list_heartbeat_runs#

List recent heartbeat runs for an agent. Shows which consumers were contacted and outcomes.

Scope: analytics:read

Link agents together so one agent can call another as a tool during chat. A general-purpose AV front-desk agent can route programming questions to a Crestron specialist agent and DSP questions to a Biamp specialist agent.

list_agent_links#

List agents linked to an agent.

Scope: apps:read

list_available_agents#

List agents available to link to an agent (agents in the same organization not already linked).

Scope: apps:read

link_agent#

Link another agent to this agent so it can be called as a tool during chat.

Scope: apps:write

Example:

"Link the 'Q-SYS Lua Specialist' agent to my 'AV Help Desk' agent"

unlink_agent#

Remove an agent link.

Scope: apps:write

Manage external database connections attached to agents. Supported types: postgres, mysql, mssql, bigquery, snowflake, clickhouse. Connect a project tracker, an inventory database, or a service-ticket warehouse.

list_database_connections#

List external database connections for an agent.

Scope: apps:read

get_database_connection#

Get details about a database connection.

Scope: apps:read

create_database_connection#

Create a new external database connection for an agent. Connection strings are encrypted at rest.

Scope: apps:write

delete_database_connection#

Delete a database connection from an agent.

Scope: apps:write

test_database_connection#

Test a database connection and discover its schema (tables, columns, types).

Scope: apps:write

Manage credit packages that consumers can purchase within your agent. Useful if you sell branded AV expert agents directly to clients or end-users.

list_consumer_packages#

List credit packages available for consumers to purchase in an agent.

Scope: apps:read

create_consumer_package#

Create a new credit package for consumer purchase. Supports one-time and subscription packages.

Scope: apps:write

update_consumer_package#

Update a consumer credit package.

Scope: apps:write

delete_consumer_package#

Delete a consumer credit package (soft delete).

Scope: apps:write

get_monetization_stats#

Get monetization analytics for an agent: total revenue, purchases, active subscriptions, and unique customers.

Scope: analytics:read

Permission scopes#

Common error codes#

• Common Workflows. Step-by-step examples.
• Rate Limits. Usage limits and best practices.
• Authentication. Token management.

*AVCodex · Your AV expertise. Amplified by AI.*