# Tools Reference

Complete reference for all Chipp MCP Server tools


This guide documents all 78 tools available in the Chipp MCP Server, organized by category.

## Quick Reference

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

| Category | Tools | Description |
|----------|-------|-------------|
| [Help](#help) | 1 | Search documentation |
| [Apps](#apps) | 6 | Create, read, update, delete applications |
| [Config](#configuration) | 7 | System prompts, models, settings, branding |
| [Knowledge](#knowledge-sources) | 6 | Add URLs, documents, manage RAG sources |
| [Analytics](#analytics) | 14 | Usage data, conversations, metrics |
| [Tags](#tags) | 8 | Intent tagging and utterance generation |
| [Evals](#evaluations) | 8 | Quality testing and evaluation |
| [Custom Actions](#custom-actions) | 5 | API integrations |
| [MCP Integrations](#mcp-integrations) | 5 | External MCP servers |
| [Deployments](#deployments) | 8 | Slack, WhatsApp, Email, Voice |
| [Workspaces](#workspaces) | 6 | Workspace and billing info |
| [Prompt Engineering](#prompt-engineering) | 7 | AI-assisted prompt improvement |

---

## Help

Tools for finding information about the MCP server itself.

### search_documentation

Search the MCP server documentation to find information about tools, authentication, setup, and best practices.

**Scope:** None (public - no authentication required)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Search query (3-500 chars) |
| limit | number | No | Max results (1-10, default 5) |
| section | string | No | Filter by section (setup, authentication, rate-limits, tools-reference, workflows) |

**Example:**
```
"Search docs for how to authenticate"
"Search documentation for rate limits"
"Find docs about creating apps"
```

<Callout type="tip">
  This tool doesn't require authentication, making it useful for onboarding new users who haven't connected yet.
</Callout>

---

## Apps

Core CRUD operations for managing Chipp applications.

### list_apps

List all applications accessible to the authenticated user.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspaceId | number | No | Filter to a specific workspace |
| limit | number | No | Max results (1-100, default 20) |
| offset | number | No | Pagination offset |
| includeDeleted | boolean | No | Include soft-deleted apps |

**Example:**
```
"List all my Chipp apps"
"Show apps in workspace 42"
```

---

### get_app

Get detailed information about a specific application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

**Example:**
```
"Get details for app 123"
"Show me the configuration of my FAQ bot"
```

---

### create_app

Create a new application in a workspace.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | App name (1-100 chars) |
| workspaceId | number | Yes | Workspace to create in |
| description | string | No | App description (max 2000 chars) |
| systemPrompt | string | No | Initial system prompt (max 10000 chars) |
| model | string | No | Model ID (default: GPT_4_1) |

**Example:**
```
"Create a customer support bot called HelpDesk in workspace 5"
"Make a new app named FAQ Bot with a helpful assistant prompt"
```

---

### update_app

Update an existing application's properties.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| name | string | No | New name |
| description | string | No | New description |
| systemPrompt | string | No | New system prompt |
| model | string | No | New model ID |
| startingMessage | string | No | Initial bot message |

**Example:**
```
"Rename app 123 to 'Support Bot v2'"
"Update the system prompt for my FAQ app to be more friendly"
```

---

### delete_app

Soft-delete an application.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

**Example:**
```
"Delete app 123"
"Remove the test app I created"
```

---

### chat_with_app

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

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| message | string | Yes | Message to send |
| sessionId | string | No | Continue existing session |

<Callout type="tip">
  Use this tool to test your apps after making changes. It's faster than switching to the web UI.
</Callout>

**Example:**
```
"Test my FAQ bot with the question 'What are your hours?'"
"Send 'hello' to app 123 to check if it's working"
```

---

## Configuration

Manage application settings, system prompts, and branding.

### get_system_prompt

Get the system prompt for an application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_system_prompt

Update an application's system prompt.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| prompt | string | Yes | New system prompt |

<Callout type="warning">
  Changes take effect immediately for new conversations. Use `chat_with_app` to test before deploying to users.
</Callout>

---

### get_model

Get the AI model configuration for an application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_model

Change the AI model for an application.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application 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 |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_settings

Update application settings including RAG options.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| temperature | number | No | Model temperature (0-2) |
| maxTokens | number | No | Max response tokens |
| enableRag | boolean | No | Enable/disable RAG |
| topK | number | No | Number of RAG chunks to retrieve |

---

### update_branding

Update visual branding for the application.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| primaryColor | string | No | Hex color code |
| logoUrl | string | No | URL to logo image |
| chatBackgroundUrl | string | No | Background image URL |

---

## Knowledge Sources

Manage RAG (Retrieval-Augmented Generation) knowledge bases.

### list_knowledge_sources

List all knowledge sources for an application.

**Scope:** `knowledge:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| status | string | No | Filter by status (PENDING, PROCESSING, COMPLETED, FAILED) |

---

### get_knowledge_source

Get details about a specific knowledge source.

**Scope:** `knowledge:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| sourceId | number | 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 |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| url | string | Yes | URL to crawl |
| crawlDepth | number | No | How many levels deep to crawl (1-3) |
| name | string | No | Custom name for the source |

<Callout type="info">
  **Smart Detection:** YouTube URLs extract transcripts, social media extracts content, regular URLs are crawled.
</Callout>

**Example:**
```
"Add https://docs.example.com to my FAQ app with crawl depth 2"
"Add this YouTube video to my training bot's knowledge base"
```

---

### add_document_source

Upload a document as a knowledge source.

**Scope:** `knowledge:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| content | string | Yes | Base64-encoded file content |
| filename | string | Yes | Original filename with extension |
| mimeType | string | No | MIME type of the file |

**Supported formats:** PDF, DOCX, TXT, MD, CSV, JSON, HTML, PPTX, XLSX, code files (JS, TS, PY, etc.)

---

### delete_knowledge_source

Remove a knowledge source from an application.

**Scope:** `knowledge:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| sourceId | number | Yes | Knowledge source ID |

---

### refresh_knowledge_source

Re-crawl or re-process a knowledge source to update its content.

**Scope:** `knowledge:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| sourceId | number | Yes | Knowledge source ID |

---

## Analytics

Access usage data, conversations, and metrics.

### get_app_analytics

Get summary analytics for an application.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| period | string | No | Time period (7d, 30d, 90d, all) |

**Returns:** Message count, conversation count, unique users, satisfaction scores.

---

### search_conversations

Search conversations with filters.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| query | string | No | Search text in messages |
| startDate | string | No | ISO date string |
| endDate | string | No | ISO date string |
| limit | number | No | Max results (default 20) |
| offset | number | No | Pagination offset |

**Example:**
```
"Find conversations about refunds in my support bot"
"Show recent conversations from the last week"
```

---

### get_conversation

Get a specific conversation with all messages.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| conversationId | string | Yes | Conversation/session ID |

---

### get_top_queries

Get the most common user queries.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| limit | number | No | Number of queries (default 20) |
| period | string | No | Time period |

---

### search_messages

Search individual messages across conversations.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| query | string | Yes | Search text |
| limit | number | No | Max results |

---

### export_conversations

Export conversations to JSON format.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| startDate | string | No | Start date filter |
| endDate | string | No | End date filter |
| format | string | No | Export format (json) |

---

### get_tag_analytics

Get analytics for message tagging.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| period | string | No | Time period |

---

### get_model_usage

Get model usage breakdown by model type.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| period | string | No | Time period |

---

### get_moderation_stats

Get content moderation statistics.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_user_memories

Get extracted user memories for an application.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| limit | number | No | Max results |

---

### get_file_analytics

Get statistics about file uploads and usage.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_popular_apps

Get most popular apps by usage.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| limit | number | No | Number of apps |

---

## Tags

Manage intent tags for message classification and automated responses.

### list_tags

List all tags for an application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_tag

Get details for a specific tag including utterances.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| tagId | string | Yes | Tag ID |

---

### create_tag

Create a new intent tag.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application 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 AI response with fixed text
- `freeze`: Stop conversation flow
- `notification`: Send webhook or email alert

**Example:**
```
"Create a tag called 'pricing' for my sales bot with utterances like 'how much does it cost'"
```

---

### update_tag

Update an existing tag.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| tagId | 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 |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| tagId | string | Yes | Tag ID |

---

### list_tag_instances

List messages that matched a specific tag.

**Scope:** `analytics:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| tagId | string | Yes | Tag ID |
| limit | number | No | Max results |

---

### remove_tag_instance

Remove a tag match from a message (false positive correction).

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instanceId | string | Yes | Tag instance ID |

---

### generate_utterances

Use AI to generate training utterances for a tag.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| prompt | string | Yes | Description of the intent |
| count | number | No | Number of utterances (1-500, default 200) |
| style | string | No | conversational, formal, or mixed |
| domain | string | No | Context (e.g., "e-commerce", "healthcare") |
| existingUtterances | string[] | No | Utterances to avoid duplicating |
| tagId | string | No | Save directly to this tag |

<Callout type="tip">
  Generate 200+ utterances for better tag matching accuracy. Specify a domain for more relevant examples.
</Callout>

**Example:**
```
"Generate 100 utterances for detecting pricing questions in an e-commerce context"
```

---

## Evaluations

Create and run quality tests for your applications.

### list_evals

List all evaluations for an application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_eval

Get details for a specific evaluation.

**Scope:** `apps:read`

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

---

### create_eval

Create a new evaluation from a conversation.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| name | string | Yes | Evaluation name |
| chatSessionId | string | No | Create from existing conversation |
| testCases | object[] | No | Manual test cases |

**Test case format:**
```json
{
  "input": "What are your hours?",
  "expectedOutput": "We're open 9-5 Monday through Friday",
  "criteria": ["mentions hours", "includes days"]
}
```

---

### update_eval

Update an existing evaluation.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| evalId | string | Yes | Evaluation ID |
| name | string | No | New name |
| testCases | object[] | No | Updated test cases |

---

### delete_eval

Delete an evaluation.

**Scope:** `apps:write`

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

---

### run_eval

Execute an evaluation and get results.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| evalId | string | Yes | Evaluation ID |
| format | string | No | Output format: "json" or "terminal" |

<Callout type="info">
  Use `format: "terminal"` for beautiful ASCII-formatted results in Claude Code:
  ```
  ┌─────────────────────────────────────────┐
  │           Evaluation Results            │
  ├─────────────────────────────────────────┤
  │ Pass Rate: ████████░░ 80%               │
  │ Avg Score: 0.85                         │
  └─────────────────────────────────────────┘
  ```
</Callout>

---

### list_eval_results

List past evaluation runs.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| evalId | 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 |
|-----------|------|----------|-------------|
| resultId | string | Yes | Result ID |

---

## Custom Actions

Manage API integrations for your applications.

### list_custom_actions

List all custom actions for an application.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_custom_action

Get details for a specific custom action.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| actionId | string | Yes | Action ID |

---

### create_custom_action

Create a new API integration.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application 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 |
| bodyTemplate | string | No | Request body template |
| parameters | object[] | No | Input parameters |

<Callout type="info">
  Custom actions have complex schemas. See the [Custom Actions Guide](/docs/guides/custom-actions) for detailed examples.
</Callout>

---

### update_custom_action

Update an existing custom action.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| actionId | 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 |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| actionId | string | Yes | Action ID |

---

## MCP Integrations

Connect external MCP servers to your applications.

### list_mcp_integrations

List all connected MCP servers for an application.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_mcp_integration

Get details about a connected MCP server.

**Scope:** `actions:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| integrationId | string | Yes | Integration ID |

---

### connect_mcp_server

Connect an external MCP server to an application.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| name | string | Yes | Display name |
| url | string | Yes | MCP server URL |
| apiKey | string | No | Authentication key |

---

### update_mcp_integration_tools

Enable or disable specific tools from a connected MCP server.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| integrationId | string | Yes | Integration ID |
| enabledTools | string[] | Yes | List of tool names to enable |

---

### disconnect_mcp_server

Remove an MCP server connection.

**Scope:** `actions:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| integrationId | string | Yes | Integration ID |

---

## Deployments

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

### list_slack_deployments

List Slack workspace connections.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_slack_deployment

Get details about a Slack deployment.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| deploymentId | string | Yes | Deployment ID |

---

### disconnect_slack_deployment

Remove a Slack connection.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| deploymentId | string | Yes | Deployment ID |

---

### get_whatsapp_deployment

Get WhatsApp business configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### get_voice_config

Get voice agent configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_voice_config

Update voice agent settings.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| voiceId | string | No | Voice model ID |
| language | string | No | Language code |
| telephonyEnabled | boolean | No | Enable phone number |

---

### get_email_deployment

Get email channel configuration.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_email_deployment

Update email channel settings.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| enabled | boolean | No | Enable/disable email |
| fromName | string | No | Sender display name |

---

## Workspaces

Manage workspaces, members, and billing information.

### 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 |
|-----------|------|----------|-------------|
| workspaceId | number | Yes | Workspace ID |

---

### list_workspace_members

List members of a workspace.

**Scope:** `workspace:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workspaceId | number | Yes | Workspace ID |

---

### 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 detailed usage breakdown.

**Scope:** `billing:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| period | string | No | Time period |

---

## Prompt Engineering

AI-assisted tools for improving prompts and selecting models.

### improve_system_prompt

Use AI to improve an existing system prompt.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| feedback | string | No | Specific feedback to incorporate |
| focus | string | No | Area to focus on (tone, clarity, etc.) |

<Callout type="tip">
  These tools use Claude to analyze your app and suggest improvements.
</Callout>

---

### generate_system_prompt

Generate a new system prompt from a description.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| description | string | Yes | What the app should do |
| tone | string | No | Desired tone (professional, friendly, etc.) |
| constraints | string[] | No | Things the app should avoid |

---

### list_suggestions

Get suggested improvements for an application.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### update_suggestions

Mark suggestions as applied or dismissed.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| suggestionId | string | Yes | Suggestion ID |
| status | string | Yes | applied or dismissed |

---

### generate_suggestions

Generate new improvement suggestions.

**Scope:** `apps:write`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |

---

### list_available_models

List all AI models available for use.

**Scope:** `apps:read`

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

---

### recommend_model

Get AI-powered model recommendations for your use case.

**Scope:** `apps:read`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | number | Yes | Application ID |
| priority | string | No | cost, quality, or speed |

---

## Appendix

### Permission Scopes

| Scope | Description |
|-------|-------------|
| `apps:read` | Read app configurations |
| `apps:write` | Create, update, delete apps |
| `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 ID is correct |
| `RATE_LIMITED` | Too many requests | Wait and retry |
| `VALIDATION_ERROR` | Invalid parameters | Check parameter types/values |

---

## Next Steps

- [Common Workflows](/docs/guides/mcp/workflows) - Step-by-step examples
- [Rate Limits](/docs/guides/mcp/rate-limits) - Usage limits and best practices
- [Authentication](/docs/guides/mcp/authentication) - Token management