# Tools Reference

Complete reference for every AVCodex MCP Server tool.

---

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

## Quick reference

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

| Category | Tools | Description |
|----------|-------|-------------|
| [Apps](#apps) | 13 | Create, publish, duplicate, rollback, and deploy agents |
| [Config](#configuration) | 9 | System prompts, models, settings, branding, suggestions |
| [Knowledge](#knowledge-sources) | 13 | Add URLs, documents, text, link sources, crawl monitoring |
| [Analytics](#analytics) | 14 | Usage data, conversations, metrics, search, moderation |
| [Tags](#tags) | 8 | Intent tagging, classification, utterance generation |
| [Evals](#evaluations) | 8 | Quality testing and evaluation |
| [Custom Actions](#custom-actions) | 6 | API integrations and testing |
| [MCP Integrations](#mcp-integrations) | 6 | External MCP servers and hosted integrations |
| [Deployments](#deployments) | 10 | Slack, WhatsApp, Discord, GitHub, Email, Voice |
| [Consumers](#consumers) | 4 | End-user management and memory |
| [Workspaces](#workspaces) | 4 | Workspace management |
| [Billing](#billing) | 5 | Subscription, credits, usage, capabilities |
| [Prompt Engineering](#prompt-engineering) | 5 | AI-assisted prompt improvement and suggestions |
| [Action Collections](#action-collections) | 10 | Reusable action bundles with sharing |
| [Variables](#variables) | 5 | Application config variables |
| [Heartbeat](#heartbeat) | 3 | Proactive messaging configuration and history |
| [Agent Links](#agent-links) | 4 | Agent-to-agent delegation |
| [Database Connections](#database-connections) | 5 | External database connections |
| [Monetization](#monetization) | 5 | Consumer credit packages |

> **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.

---

## Apps

Core CRUD operations for managing AVCodex agents.

### list_apps

List every agent accessible to the authenticated user.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspace_id | string | No | Filter to a specific workspace |
| limit | number | No | Max results (1-100, default 20) |
| offset | number | No | Pagination offset |

**Example:**
```
"List all my AVCodex agents"
"Show agents in workspace 42"
```

---

### get_app

Get detailed information about a specific agent.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Agent name (1-100 chars) |
| workspace_id | string | Yes | Workspace to create in |
| description | string | No | Agent description (max 2000 chars) |
| system_prompt | string | No | Initial system prompt. Server accepts up to 2M chars; the builder UI cap is derived per-model from the context window (~50% of the window at 4 chars/token). |
| model_id | string | No | Model ID (default: GPT_4_1) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | No | New name |
| description | string | No | New description |
| is_public | boolean | No | Make agent publicly listed |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| message | string | Yes | Message to send |
| session_id | string | No | Continue an existing session |

> **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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Search query to match against agent names and descriptions |
| limit | number | No | Max results (default 10) |

---

### publish_app

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| tag | string | No | Version tag/label (e.g. `v2.0`, `bugfix`) |

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

---

### list_app_versions

List published version history for an agent.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| limit | number | No | Max results (default 20) |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID to duplicate |
| name | string | No | Name for the copy (default: `Original Name (Copy)`) |
| workspace_id | string | No | Target workspace (defaults to same workspace) |

---

### restore_app_version

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| version_id | string | Yes | Version ID to restore (from `list_app_versions`) |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| version_id | string | Yes | Version ID to rollback to (must be a previously launched version) |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**Returns:** `consumer_url`, `default_url`, `has_custom_domain`, and `embed_snippet`.

---

## Configuration

Manage agent settings, system prompts, and branding.

### get_system_prompt

Get the system prompt for an agent.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_system_prompt

Update an agent's system prompt.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| system_prompt | string | Yes | New system prompt text |

> **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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_model

Change the AI model for an agent.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| model | string | Yes | Model ID (e.g., GPT_4_1, CLAUDE_3_5_SONNET) |

---

### get_settings

Get detailed settings including RAG configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_settings

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| settings | object | No | Settings JSONB (auth, chat options, etc.) |
| capabilities | object | No | Capabilities JSONB (features to enable/disable) |
| welcome_messages | string[] | No | Welcome message rotation |
| suggested_messages | string[] | No | Conversation starter suggestions shown to users |

---

### update_branding

Update visual branding for the agent.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| primary_color | string | No | Hex color code (e.g. `#3B82F6`) |
| logo_url | string | No | URL to logo image (light mode) |
| logo_url_dark | string | No | URL to logo image (dark mode) |
| input_text_hint | string | No | Placeholder text for the chat input |
| disclaimer_text | string | No | Disclaimer shown below the chat |

---

### list_suggestions

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

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_suggestions

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| suggestions | string[] | Yes | Array of suggestion strings (max 6 recommended) |

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

---

## Knowledge Sources

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| status | string | No | Filter by status: `pending`, `processing`, `completed`, `failed` |
| type | string | No | Filter by type: `url`, `file`, `text`, `youtube`, `youtube_channel`, `sitemap`, `confluence` |
| limit | number | No | Max results (default 50) |
| offset | number | No | Pagination offset |

---

### get_knowledge_source

Get details about a specific knowledge source.

**Scope:** `knowledge:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID |

---

### add_url_source

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

**Scope:** `knowledge:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| url | string | Yes | URL to crawl |
| max_depth | number | No | How many levels deep to crawl links (default 1) |
| crawl_links | boolean | No | Whether to follow links on the page |
| max_pages | number | No | Maximum number of pages to crawl |
| name | string | No | Custom name for the source |

> **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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| content | string | Yes | Text content to add |
| name | string | Yes | Name for the source |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID |

---

### list_active_crawls

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

**Scope:** `knowledge:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID to cancel |

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.).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| files | object[] | Yes | Array of files (1 to 20) |

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID to link |
| target_app_id | string | Yes | Agent ID to link the source to |

---

### unlink_knowledge_source

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

**Scope:** `knowledge:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source_id | string | Yes | Knowledge source ID |
| app_id | string | Yes | Agent ID to unlink from |

---

### list_linked_knowledge_sources

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

**Scope:** `knowledge:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

## Analytics

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

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

---

### search_conversations

Search conversations with filters.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| query | string | No | Text to search for in messages |
| since | string | No | ISO date to filter from |
| limit | number | No | Max results (default 20) |
| offset | number | No | Pagination offset (default 0) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| session_id | string | Yes | Session ID |

---

### get_top_queries

Get the most common user queries.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| limit | number | No | Number of queries (default 20) |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

---

### get_model_usage

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

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

---

### get_response_time_analytics

Get response time statistics based on message timestamps.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 7 days) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

---

### search_messages

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

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| query | string | Yes | Text to search for |
| role | string | No | Filter by role: `user`, `assistant`, or `system` |
| since | string | No | ISO date to filter from |
| limit | number | No | Max results (default 50, max 200) |
| offset | number | No | Pagination offset (default 0) |

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| query | string | Yes | Text to search for in knowledge content |
| limit | number | No | Max results (default 20) |

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | No | ISO date to filter from (defaults to last 30 days) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| since | string | No | ISO date to filter from (defaults to last 30 days) |
| limit | number | No | Max results (default 10) |

---

### export_conversations

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

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| since | string | Yes | ISO date to export from (e.g. `2026-01-01`) |
| until | string | No | ISO date to export until (defaults to now) |
| limit | number | No | Max sessions to export (default 100, max 500) |

---

## Tags

Manage intent tags for message classification and automated responses.

### list_tags

List all tags for an agent.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_tag

Get details for a specific tag, including utterances.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tag_id | string | Yes | Tag ID |

---

### create_tag

Create a new intent tag.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Tag name |
| description | string | No | Tag description |
| utterances | string[] | No | Example phrases that match this tag |
| action | object | No | Action to take when tag matches |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| tag_id | string | Yes | Tag ID |
| name | string | No | New name |
| utterances | string[] | No | New utterances |
| action | object | No | New action |

---

### delete_tag

Delete a tag.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| tag_id | string | Yes | Tag ID |

---

### list_tag_instances

List messages that matched a specific tag.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| tag_id | string | No | Filter by specific tag (optional) |
| limit | number | No | Max results (default 50) |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tag_instance_id | string | Yes | Tag instance ID to remove |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tag_name | string | Yes | The tag name (e.g. `wants quote`, `network outage`) |
| tag_description | string | Yes | Description of what this tag detects |
| count | number | No | Number of utterances to generate (default 20, max 100) |

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

---

## Evaluations

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_eval

Get details for a specific evaluation.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| eval_id | string | Yes | Evaluation ID |

---

### create_eval

Create a new evaluation with test cases for an agent.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Evaluation name |
| test_cases | object[] | Yes | Array of test cases |
| evaluation_method | string | No | `factuality`, `faithfulness`, `answer_relevancy`, `context_relevancy`, or `comprehensive` (default: `factuality`) |

**Test case format:**
```json
{
  "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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| eval_id | string | Yes | Evaluation ID |
| name | string | No | New name |
| test_cases | object[] | No | Updated test cases |
| evaluation_method | string | No | New evaluation method |

---

### delete_eval

Delete an evaluation.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| eval_id | string | Yes | Evaluation ID |

---

### run_eval

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| eval_id | string | Yes | Evaluation ID |

---

### list_eval_results

List past evaluation runs.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| eval_id | string | Yes | Evaluation ID |
| limit | number | No | Max results |

---

### get_eval_result

Get detailed results from a specific evaluation run.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| result_id | string | Yes | Result ID |

---

## Custom Actions

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_custom_action

Get details for a specific custom action.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| action_id | string | Yes | Action ID |

---

### create_custom_action

Create a new API integration.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Action name |
| description | string | Yes | What the action does |
| method | string | Yes | HTTP method (GET, POST, etc.) |
| url | string | Yes | API endpoint URL |
| headers | object | No | Request headers |
| body_template | string | No | Request body template |
| parameters | object[] | No | Input parameters |

> **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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| action_id | string | Yes | Action ID |
| (other fields) | various | No | Fields to update |

---

### delete_custom_action

Delete a custom action.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| action_id | string | Yes | Action ID |

---

### test_custom_action

Test a custom action by executing it with sample parameters.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| action_id | string | Yes | Action ID |
| parameters | object | No | Test parameters to pass |

---

## MCP Integrations

Connect external MCP servers to your agents.

### list_mcp_integrations

List all connected MCP servers for an agent.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_mcp_integration

Get details about a connected MCP server.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| integration_id | string | Yes | Integration ID |

---

### connect_mcp_server

Connect an external MCP server to an agent.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| server_url | string | Yes | MCP server URL (must be HTTPS) |
| name | string | No | Display name (defaults to server URL) |
| auth_type | string | No | Authentication type: `NONE`, `BEARER`, or `OAUTH` (default: `NONE`) |
| auth_token | string | No | Bearer token (when `auth_type` is `BEARER`) |

---

### update_mcp_integration_tools

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

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| integration_id | string | Yes | Integration ID |
| is_active | boolean | No | Enable or disable the entire integration |
| enabled_tools | string[] | No | Tool names to enable (unlisted tools are disabled) |

---

### disconnect_mcp_server

Remove an MCP server connection.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| integration_id | string | Yes | Integration ID |

---

### list_hosted_integrations

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

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

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

---

## Deployments

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

### list_slack_deployments

List Slack workspace connections.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_slack_deployment

Get details about a Slack deployment.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| deployment_id | string | Yes | Deployment ID |

---

### disconnect_slack_deployment

Remove a Slack connection.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| deployment_id | string | Yes | Deployment ID |

---

### get_whatsapp_deployment

Get WhatsApp business configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_voice_config

Get voice agent configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_voice_config

Update voice agent settings.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| voice_id | string | No | Voice model ID |
| language | string | No | Language code |
| telephony_enabled | boolean | No | Enable phone number |

---

### get_email_deployment

Get email channel configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_email_deployment

Update email channel settings.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| enabled | boolean | No | Enable/disable email |
| from_name | string | No | Sender display name |

---

### get_discord_deployment

Get the Discord bot integration status for an agent.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

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

---

## Consumers

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| search | string | No | Search by name, email, or identifier |
| has_email | boolean | No | Filter to consumers with/without email |
| sort_by | string | No | `created_at`, `credits`, `name`, or `email` (default: `created_at`) |
| sort_dir | string | No | `asc` or `desc` (default: `desc`) |
| limit | number | No | Max results (default 25, max 100) |
| offset | number | No | Pagination offset (default 0) |

---

### get_consumer

Get details about a specific consumer including their session count.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| consumer_id | string | Yes | Consumer ID |

---

### update_consumer

Update a consumer's credit balance or subscription status.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| consumer_id | string | Yes | Consumer ID |
| credits | number | No | Set credit balance (integer >= 0) |
| subscription_active | boolean | No | Enable or disable the subscription |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| consumer_id | string | Yes | Consumer ID |
| memory_type | string | No | Filter by memory type (optional) |
| limit | number | No | Max memories to return (default 50) |

Only active (non-superseded) memories are returned.

---

## Workspaces

Manage workspaces and team members.

### list_workspaces

List all workspaces you have access to.

**Scope:** `workspace:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | | | |

---

### get_workspace

Get details about a specific workspace.

**Scope:** `workspace:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspace_id | string | Yes | Workspace ID |

---

### list_workspace_members

List members of a workspace.

**Scope:** `workspace:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspace_id | string | Yes | Workspace ID |

---

### create_workspace

Create a new workspace in your organization.

**Scope:** `workspace:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Workspace name |

**Example:**
```
"Create a new workspace called Service Operations"
```

---

## Billing

View subscription and credit information.

### get_subscription

Get subscription details for an organization.

**Scope:** `billing:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | | | |

---

### get_credits

Get credit balance and usage.

**Scope:** `billing:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | | | |

---

### get_usage

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

**Scope:** `billing:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| since | string | No | ISO date to filter from (defaults to last 30 days) |

---

### get_usage_by_app

Get token usage broken down by agent for the organization.

**Scope:** `billing:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| since | string | No | ISO date to filter from (defaults to last 30 days) |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | | | |

---

## Prompt Engineering

AI-assisted tools for improving prompts and selecting models.

### list_available_models

List all AI models available for use.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | | | |

---

### generate_system_prompt

Generate a new system prompt from a description.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| description | string | Yes | What the agent should do, its personality, and target audience |
| tone | string | No | Desired tone (professional, friendly, technical, casual) |

---

### improve_system_prompt

Use AI to analyze and improve an existing system prompt.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| system_prompt | string | Yes | The current system prompt to improve |
| focus | string | No | What to focus on: `clarity`, `safety`, `personality`, `instructions`, `all` (default: `all`) |

---

### recommend_model

Get AI-powered model recommendations for your use case.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| use_case | string | Yes | Description of the use case (e.g. tier-1 control system support, RFP scope generation) |
| priority | string | No | `quality`, `speed`, or `cost` (default: `quality`) |

---

### 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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| count | number | No | Number of suggestions to generate (default 4, max 10) |
| style | string | No | `question`, `task`, `exploratory`, or `mixed` (default: `mixed`) |

**Example:**
```
"Generate 6 starter suggestions for my Q-SYS support agent"
```

---

## Action Collections

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspace_id | string | No | Filter by workspace |

---

### get_action_collection

Get details for a specific action collection.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collection_id | string | Yes | Collection ID |

---

### create_action_collection

Create a new action collection.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Collection name |
| description | string | No | Collection description |
| workspace_id | string | No | Workspace to create in |

---

### update_action_collection

Update an action collection's name or description.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collection_id | string | Yes | Collection ID |
| name | string | No | New collection name |
| description | string | No | New collection description |

---

### delete_action_collection

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

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collection_id | string | Yes | Collection ID |

---

### link_collection_to_app

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

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| collection_id | string | Yes | Collection ID |

---

### unlink_collection_from_app

Remove an action collection from an agent.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| collection_id | string | Yes | Collection ID |

---

### list_linked_collections

List all action collections linked to a specific agent.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### update_collection_sharing

Update the sharing scope of an action collection.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collection_id | string | Yes | Collection ID |
| sharing_scope | string | Yes | `PRIVATE`, `WORKSPACE`, or `PUBLIC` |

- **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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collection_id | string | Yes | Collection ID to import from |
| app_id | string | Yes | Agent ID to import into |

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

---

## Variables

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_app_variable

Get details for a specific agent variable.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| variable_id | string | Yes | Variable ID |

---

### create_app_variable

Create a new agent variable.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Variable name |
| label | string | No | Display label |
| type | string | No | Variable type |
| description | string | No | Variable description |
| required | boolean | No | Whether the variable is required |

---

### update_app_variable

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| variable_id | string | Yes | Variable ID |
| value | string | No | New variable value |
| label | string | No | New display label |
| description | string | No | New description |

---

### delete_app_variable

Delete an agent variable.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| variable_id | string | Yes | Variable ID |

---

## Heartbeat

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

**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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| enabled | boolean | No | Enable or disable heartbeat |
| every | string | No | Interval (e.g. `30m`, `1h`, `4h`, `1d`) |
| prompt | string | No | Custom prompt for heartbeat messages |
| checklist | string | No | Criteria for what the heartbeat should check |
| targets | string[] | No | Delivery channels: `whatsapp`, `slack`, `email`, `webchat`, `webhook` |
| model | string | No | LLM model to use for heartbeat messages |

---

### list_heartbeat_runs

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

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| limit | number | No | Max results (default 20) |

---

## Agent Links

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### list_available_agents

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

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### link_agent

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Source agent ID (the agent that will call the linked agent) |
| target_app_id | string | Yes | Target agent ID (the agent to link) |

**Example:**
```
"Link the 'Q-SYS Lua Specialist' agent to my 'AV Help Desk' agent"
```

---

### unlink_agent

Remove an agent link.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Source agent ID |
| target_app_id | string | Yes | Target agent ID to unlink |

---

## Database Connections

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### get_database_connection

Get details about a database connection.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| connection_id | string | Yes | Connection ID |

---

### create_database_connection

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Display name |
| db_type | string | Yes | `postgres`, `mysql`, `mssql`, `bigquery`, `snowflake`, or `clickhouse` |
| connection_string | string | Yes | Connection string/DSN |
| default_access_level | string | No | `read` or `read_write` (default: `read`) |
| allowed_tables | string[] | No | Restrict access to specific tables (all tables if omitted) |
| max_rows | number | No | Max rows per query result (default: 1000) |

---

### delete_database_connection

Delete a database connection from an agent.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| connection_id | string | Yes | Connection ID |

---

### test_database_connection

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| connection_id | string | Yes | Connection ID |

---

## Monetization

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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

### create_consumer_package

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

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| name | string | Yes | Package name (e.g. `Service Pack`) |
| type | string | Yes | `ONE_TIME` or `SUBSCRIPTION` |
| credits | number | Yes | Number of credits in the package |
| price_cents | number | Yes | Price in cents (e.g. `999` = $9.99) |
| description | string | No | Package description |
| billing_interval | string | No | For subscriptions: `month` or `year` (default: `month`) |
| sort_order | number | No | Display order (lower = first, default: 0) |

---

### update_consumer_package

Update a consumer credit package.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| package_id | string | Yes | Package ID |
| name | string | No | New name |
| credits | number | No | New credit amount |
| price_cents | number | No | New price in cents |
| description | string | No | New description |
| is_active | boolean | No | Enable/disable |
| status | string | No | `DRAFT` or `PUBLISHED` |
| sort_order | number | No | New display order |

---

### delete_consumer_package

Delete a consumer credit package (soft delete).

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |
| package_id | string | Yes | Package ID |

---

### get_monetization_stats

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

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| app_id | string | Yes | Agent ID |

---

## Appendix

### Permission scopes

| Scope | Description |
|-------|-------------|
| `apps:read` | Read agent configurations |
| `apps:write` | Create, update, delete agents |
| `knowledge:read` | Read knowledge sources |
| `knowledge:write` | Manage knowledge sources |
| `actions:read` | Read custom actions |
| `actions:write` | Manage custom actions |
| `analytics:read` | Read analytics data |
| `workspace:read` | Read workspace info |
| `billing:read` | Read billing data |
| `*` | All permissions |

### Common error codes

| Code | Description | Resolution |
|------|-------------|------------|
| `UNAUTHORIZED` | Invalid or expired token | Re-authenticate |
| `FORBIDDEN` | Insufficient scope | Request additional scopes |
| `NOT_FOUND` | Resource doesn't exist | Check the ID is correct |
| `RATE_LIMITED` | Too many requests | Wait and retry |
| `VALIDATION_ERROR` | Invalid parameters | Check parameter types and values |

---

## Next steps

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

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