# Tools Reference Complete reference for all Chipp MCP Server tools --- This guide documents the 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 | |----------|-------|-------------| | [Apps](#apps) | 16 | Create, update settings (one app or many), publish, duplicate, rollback, and deploy applications | | [Config](#configuration) | 13 | System prompts, models, settings, branding, auth, tool overrides | | [Knowledge](#knowledge-sources) | 13 | Add URLs, documents, text, link sources, crawl monitoring | | [Enterprise KB Evidence](#enterprise-kb-evidence) | 5 | Scoped evidence retrieval: discover grants, search, cite, read | | [Analytics](#analytics) | 15 | Usage data, conversations, metrics, search, moderation | | [Tags](#tags) | 10 | Intent tagging, classification, utterance generation | | [Tag Examples](#tag-examples) | 5 | Training utterances: list, create, update, bulk import | | [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 | | [Components](#components) | 11 | Component Studio custom UI: create, refine, share, link | | [Deployments](#deployments) | 12 | Slack, WhatsApp, Discord, GitHub, Email, Voice | | [Consumers](#consumers) | 6 | 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) | 4 | Proactive messaging configuration, history, manual trigger | | [Agent Links](#agent-links) | 4 | Agent-to-agent delegation | | [Database Connections](#database-connections) | 5 | External database connections | | [Monetization](#monetization) | 5 | Consumer credit packages | | [Conversation Logging](#conversation-logging) | 1 | Log externally-handled conversations into chat history | | [Discovery](#discovery) | 2 | Find agents by capability, search the integration catalog | | [App Administration](#app-administration) | 7 | Access whitelist, move app, custom domain status, Receipt Sync, workspace App Defaults | | [App Connections](#app-connections) | 6 | Integration switches, Factory per-user integrations, Vanta write access, knowledge refresh schedule | | [Utilities](#utilities) | 3 | Identity introspection, platform docs search, and the book (full text on paid plans) | **Related APIs:** the MCP server is one of three programmatic surfaces. The [Builder API](/docs/builder-api/overview) is a REST API using per-app `chipp_` keys (sessions, consumers, conversation logging over HTTP), and the [Org Export API](/docs/api/org-export) uses org-wide `chipp_org_` keys for bulk transcript export. MCP tokens (`chipp_sk_` / OAuth) are organization-scoped and cover the full tool surface below. --- ## Apps Core CRUD operations for managing Chipp applications. ### list_apps List all applications accessible to the authenticated user. **Scope:** `apps:read`. **Chipp MCP:** [`core`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | workspace_id | string | No | Filter by workspace ID (optional) | | limit | number | No | Max number of apps to return (default 20, max 50) | | offset | number | No | Pagination offset (default 0) | **Example:** ``` "List all my Chipp apps" "Show apps in workspace 42" ``` --- ### get_app Get detailed information about a specific application. **Scope:** `apps:read`. **Chipp MCP:** [`core`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The 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`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | App name | | description | string | No | App description (optional) | | workspace_id | string | Yes | Workspace to create the app in (a workspace-restricted API key defaults to its workspace) | | display_name | string | No | Client-facing display name shown in the chat header, HQ listings, and notifications. Omit or set to null to use the internal name as the display name. Max 100 chars. (optional) | | system_prompt | string | No | Initial system prompt (optional, up to 2,000,000 characters) | | model_id | string | No | LLM model ID (optional, defaults to the platform new-agent default, currently claude-sonnet-5-5). An openrouter:\ model cannot be set on create: create the app, then call update_model. | **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 app's settings. `settings` takes the same fields the Chipp Alchemist uses: name, `display_name`, description, `instructions` (the system prompt), model, temperature, capabilities, brand styles and colors, voice, auth mode, email gating, language, custom CSS, starter messages, uploads, spending limit and more. The fields you send are merged into the current config; the rest are kept. **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | settings | object | No | Fields to update Fields: `name`, `display_name`, `description`, `instructions`, `model`, `temperature`, `maxTokens`, `thinkingEffort`, `reasoningEffort`, `uptimeFallback`, `uptimeFallbackModel`, `uptimeFallbackAcceptHigherCost`, `authMode`, `domainRestriction`, `hideApprovedDomains`, `artifactFrameAncestors`, `emailGatingEnabled`, `botProtectionEnabled`, `publicLeaderboardOptIn`, `suggestedMessages`, `welcomeMessage`, `primaryColor`, `customCss`, `authCustomCss`, `isPublic`, `language`, `textDirection`, `currency`, `consumerSharingOptOut`, `capabilities`, `spendingLimitCents`, `brandStyles`, `showSources`, `multiplayerEnabled`, `multiplayerRequireAuth`, `multiplayerRequireActiveSubscription`, `greetingEnabled`, `greetingPrompt`, `fileUploadEnabled`, `imageUploadEnabled`, `audioInputEnabled`, `imageInputEnabled`, `maxImagesPerConversation`, `imageLimitReachedMessage`, `streamResponses`, `monetizationEnabled`, `trialDurationDays`, `trialUsageLimitCents`, `shareConsumerCredentialsWithLinkedAgents`, `linkedAgentMaxIterations`, `maxKnowledgeChunksPerQuery`, `ragConfig`, `fullDocumentKnowledge`, `fullDocumentMaxPages`, `fullDocumentCacheTtl`. | | reasoning | string | No | Brief explanation | Each field needs the matching workspace permission, as in the dashboard (for example, a theme needs Branding and a name needs App Settings); the spending limit needs App Settings and a plan with spending limits. `instructions`, `welcomeMessage`, `greetingPrompt` and `customCss` replace the whole value: read the current value first (`get_system_prompt`, `get_settings`) and keep what should stay. `ragConfig` tunes knowledge retrieval: `maxResults` (1-25, default 5), `minScore` (0-1, default 0.15), `vectorWeight` (0-1, default 0.7), `textWeight` (0-1, default 0.3), `useDocumentBoosting` (default true) and `documentWeight` (0-1, default 0.3). Only the keys you send change. An unknown key or an out-of-range value is refused. It takes effect after the app is re-published. See [RAG Settings](/docs/guides/rag-settings#advanced-tuning). The earlier flat parameters `name`, `display_name`, `description` and `is_public` still work. Returns `success`, the `updated` field list and a `message`; after an `instructions` change, `instructionsLength` and `instructionsPreview` show what was stored. A refused payload returns `success: false` and an `error` naming the fix (for example, a `[component:Name]` placeholder, or custom CSS that tries to hide the microphone button, which has its own toggle). **Example:** ``` "Rename app 123 to 'Support Bot v2'" "Turn on web search and switch my FAQ app to the classic-chipp theme" ``` --- ### bulk_update_app_settings Apply the same `settings` to many apps in one call (up to 200), for example a theme on every app in a workspace. Each app is written on its own: an app you cannot reach, or that fails, is listed in `failed` and never blocks the others. **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_ids | string[] | Yes | Apps to update (from get_app_overview / list_apps or search_apps). | | settings | object | Yes | Same fields as update_app's settings Fields: `name`, `display_name`, `description`, `instructions`, `model`, `temperature`, `maxTokens`, `thinkingEffort`, `reasoningEffort`, `uptimeFallback`, `uptimeFallbackModel`, `uptimeFallbackAcceptHigherCost`, `authMode`, `domainRestriction`, `hideApprovedDomains`, `artifactFrameAncestors`, `emailGatingEnabled`, `botProtectionEnabled`, `publicLeaderboardOptIn`, `suggestedMessages`, `welcomeMessage`, `primaryColor`, `customCss`, `authCustomCss`, `isPublic`, `language`, `textDirection`, `currency`, `consumerSharingOptOut`, `capabilities`, `spendingLimitCents`, `brandStyles`, `showSources`, `multiplayerEnabled`, `multiplayerRequireAuth`, `multiplayerRequireActiveSubscription`, `greetingEnabled`, `greetingPrompt`, `fileUploadEnabled`, `imageUploadEnabled`, `audioInputEnabled`, `imageInputEnabled`, `maxImagesPerConversation`, `imageLimitReachedMessage`, `streamResponses`, `monetizationEnabled`, `trialDurationDays`, `trialUsageLimitCents`, `shareConsumerCredentialsWithLinkedAgents`, `linkedAgentMaxIterations`, `maxKnowledgeChunksPerQuery`, `ragConfig`, `fullDocumentKnowledge`, `fullDocumentMaxPages`, `fullDocumentCacheTtl`. | | reasoning | string | No | Brief summary of the change and why | Each app needs the same per-field workspace permissions as `update_app`. Returns `success` (true only when every app was updated), `total`, `succeeded`, `failed` (`{ appId, error }` for each app not updated; an app you cannot reach reads "not found or no access"), `updatedFields` and a `message`. Retry with only the failed ids. **Example:** ``` "Set the classic-chipp theme on every app in my Support workspace" ``` --- ### get_app_settings_help The guidance for app settings fields: what each one does, its default, when to use it, and what it is not for. Read it before you change a field such as `capabilities.memory`, `trialMode`, `sessionTerminationEnabled`, `ragConfig` or `customCss` with `update_app` or `bulk_update_app_settings`. It reads no app data. **Scope:** `apps:read`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | fields | string[] | No | Settings paths, e.g. capabilities.memory or ragConfig. Omit for every field with guidance. | Returns `fields` (the guidance text for each path) and `unknown` (paths that have no guidance). **Example:** ``` "What does session termination do before I turn it on?" ``` --- ### delete_app Soft-delete an application. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID to delete | **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`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID to chat with | | message | string | Yes | The message to send | | session_id | string | No | Session ID for continuing a conversation (optional, creates new session if omitted) | > **Tip:** Use this tool to test your apps after making changes. It's faster than switching to the web UI. **Example:** ``` "Test my FAQ bot with the question 'What are your hours?'" "Send 'hello' to app 123 to check if it's working" ``` **Response shape:** ```json { "response": "The assistant's reply text (may be empty if only a UI component rendered).", "session_id": "uuid", "model": "claude-sonnet-4-6", "component_invocations": [ { "component_id": "uuid", "component_name": "PricingTable", "props": { "tier": "STUDIO_PRO" }, "tool_call_id": "call_abc" } ], "usage": { "input_tokens": 1234, "output_tokens": 567 } } ``` `component_invocations` lists every custom UI component the app rendered during the turn (`render_` tool calls). The array is always present, empty when no components rendered. Use this when your app uses [Component Studio](/docs/guides/component-studio) and you need to see what rendered (the `response` text is often empty for component-rendering turns). --- ### search_apps Search apps by name or description across the workspaces you can reach. An API key searches its own organization unless `all_orgs` is true. **Scope:** `apps:read`. **Chipp MCP:** [`core`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Text matched case-insensitively against app names and descriptions | | limit | number | No | Max results (default 10, max 25) | | all_orgs | boolean | No | API keys: also search the user's other organizations (default false) | Returns `apps` (each with its `slug`, workspace and organization), `count`, the `query`, your `current_workspace_id` and `current_organization_id`, and a `hint`. A UUID never matches app text, so a UUID query is refused with a pointer to `get_app`. --- ### publish_app Publish the current app configuration to make it live for consumers. Creates a version snapshot and deploys it. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID to publish | | tag | string | No | Optional 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 app. **Scope:** `apps:read`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | limit | number | No | Max results (default 20, max 100) | --- ### duplicate_app Create a copy of an existing app with all its configuration, system prompt, and settings. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID to duplicate | | name | string | No | Name for the copy (default: 'Original Name (Copy)') | | workspace_id | string | No | Target workspace (optional, defaults to same workspace) | | include_tags | boolean | No | Copy the source app's tags + example utterances onto the clone (notification destinations preserved unless reset). Default true. | | reset_tag_notifications | boolean | No | OPT-IN, default false. Copy tags with notifications off and no email, channels or webhook. | | include_evals | boolean | No | Copy the source app's evals + test cases + publish config onto the clone (no run history/scores). Default true. | --- ### restore_app_version Restore an app's configuration to a previous version. Does not publish: use `publish_app` afterward if needed. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | version_id | string | Yes | The version ID to restore (from list_app_versions) | --- ### rollback_app_version Rollback an app to a previously published version and immediately publish it. Combines restore + publish in one step. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | version_id | string | Yes | The version ID to rollback to (must be a previously launched version) | --- ### get_app_url Get the consumer-facing URL for an app (custom domain, vanity subdomain, or default path). Also returns the embed widget snippet. **Scope:** `apps:read`. **Chipp MCP:** [`core`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | **Returns:** `consumer_url`, `default_url`, `has_custom_domain`, and `embed_snippet`. --- ### update_app_slug Change an app's URL slug (the short identifier in the consumer chat URL, e.g. `my-sales-bot`). **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | slug | string | Yes | New URL slug for the app (e.g. 'my-sales-bot'). Lowercase alphanumeric and hyphens only, 3-60 characters. | --- ## Configuration Manage application settings, system prompts, and branding. ### get_system_prompt Get the system prompt for an application. **Scope:** `apps:read`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### update_system_prompt Update an application's system prompt. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | system_prompt | string | Yes | The 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 application. **Scope:** `apps:read`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### update_model Change the AI model and/or temperature for an application. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | model | string | No | Model ID (e.g. claude-sonnet-4-6, gpt-4.1, gemini-2.5-pro), or openrouter:\ for an OpenRouter model | | temperature | number | No | Temperature value between 0 and 2 (optional) | --- ### get_settings Get detailed settings including RAG configuration. **Scope:** `apps:read`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### update_settings Update application settings, capabilities, welcome messages, and suggested starters. **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | settings | object | No | App settings JSONB (optional). Top-level keys are shallow-merged: sending one key preserves the rest. `settings.ragConfig` (knowledge retrieval tuning) is validated and FIELD-merged, so sending one key keeps the others: maxResults (1-25, default 5), minScore (0-1, default 0.15), vectorWeight (0-1, default 0.7), textWeight (0-1, default 0.3), useDocumentBoosting (default true), documentWeight (0-1, default 0.3), fullDocumentMode, fullDocumentMaxPages (1-600), fullDocumentCacheTtl ("5m" or "1h"). Unknown keys or out-of-range values are refused. Takes effect after re-publish. Every other key is validated against the same schema as the builder API: an unknown top-level key, an array, a JSON-encoded string or null is refused with an error that lists the valid keys, and nothing is saved. Server-managed keys returned by get_settings (embeddingConfig, nameIsSuggested, creationSource, ...) are not writable here. | | capabilities | object | No | App capabilities JSONB (optional). Top-level capability BLOCKS are shallow-merged. WARNING: capabilities.toolOverrides is REPLACED WHOLESALE: partial sends erase other overrides. Use `set_tool_override` for safe single-tool toggles. | | welcome_messages | string[] | No | Welcome messages shown to users (optional). Replaces the whole array. | | suggested_messages | string[] | No | Suggested conversation starters (optional). Replaces the whole array. | Top-level `settings` keys are shallow-merged. `settings.ragConfig` is the exception: it is validated and merged key by key, so sending `{"ragConfig": {"minScore": 0.25}}` keeps every other retrieval setting. It takes `maxResults` (1-25), `minScore`, `vectorWeight`, `textWeight` and `documentWeight` (each 0-1), `useDocumentBoosting`, plus the full-document keys `fullDocumentMode`, `fullDocumentMaxPages` (1-600) and `fullDocumentCacheTtl` (`"5m"` or `"1h"`). An unknown key or an out-of-range value fails the call and nothing is written. `"ragConfig": null` clears every retrieval setting back to the defaults. Changes take effect after re-publish. See [RAG Settings](/docs/guides/rag-settings#advanced-tuning). --- ### update_branding Update visual branding for the application. **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | primary_color | string | No | Brand primary color hex (e.g. #6366f1) | | logo_url | string | No | Logo image URL | | logo_url_dark | string | No | Logo image URL for dark mode | | input_text_hint | string | No | Placeholder text for the chat input | | disclaimer_text | string | No | Disclaimer text shown below chat input | | theme | `"default"` or `"imessage"` or `"classic-chipp"` | No | Chat theme preset | | dark_mode | `"off"` or `"on"` or `"auto"` | No | Dark mode behavior | | bot_message_color | string | No | Assistant message bubble background hex (e.g. #F3F4F6) | | user_message_color | string | No | User message bubble background hex (e.g. #4F46E5) | | bot_message_font_color | string | No | Assistant message text hex (legacy compatibility; may not render in all themes) | | user_message_font_color | string | No | User message text hex (legacy compatibility; may not render in all themes) | | chat_input_border_color | string | No | Chat input border hex (legacy compatibility; may not render in all themes) | | force_dark_mode | boolean | No | Legacy dark mode forcing flag (prefer dark_mode) | | show_tool_status | boolean | No | Show tool invocation status to consumers (legacy compatibility) | | custom_css | string | No | Custom CSS injected into the consumer chat UI. Affects all screens globally. Pass an empty string to clear. Live-on-save (no re-publish needed). | | auth_custom_css | string | No | Custom CSS injected only into the consumer auth screens (login, signup). Pass an empty string to clear. Live-on-save (no re-publish needed). | | email_display_name | string | No | Optional per-app sender/subject display name used ONLY for patient-facing system emails (OTP verification, password reset, welcome, circle invites). When set, overrides the app's branding display name for email purposes. When unset (or cleared with an empty string), emails fall back to the app's branding display name, then a neutral default -- never the internal app name/slug. | --- ### list_suggestions Get the suggested conversation starters shown to users on the chat interface. **Scope:** `apps:read`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### update_suggestions Set the suggested conversation starters shown to users. Pass an empty array to clear all suggestions. **Scope:** `apps:write`. **Chipp MCP:** [`apps`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | suggestions | string[] | Yes | Array of suggestion strings (max 6 recommended) | **Example:** ``` "Set the starter prompts for my support bot to: 'Track my order', 'Return an item', 'Speak to a human'" ``` --- ### update_auth Update an app's consumer authentication settings. All fields are optional and live-on-save (no re-publish needed). **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | auth_mode | `"open"` or `"encouraged"` or `"required"` or `"restricted"` | No | Consumer access mode (see description above) | | require_auth | boolean | No | Whether authentication is required before consumers can chat. Setting auth_mode='required' implies require_auth=true. | | signups_restricted_to_domain | string | No | If set, only email addresses from this domain (e.g. 'acme.com') may sign up as consumers. Pass an empty string to clear the restriction. | --- ### set_tool_override Toggle enable/disable or update the LLM-facing description for a single tool override on an app. **Scope:** `apps:write`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | tool_key | string | Yes | The tool key to override. This app's VALID keys are the union of: built-in tools (camelCase, e.g. 'browseWeb', 'generateVideo', 'searchKnowledge'); hosted-integration tool names (snake_case, provider-prefixed, e.g. 'slack_send_message') for integrations connected on this app; custom component tools ('render_\', e.g. 'render_personnel_file'); custom action tools (their slug/name and any short alias); and MCP integration tools ('\_\'). Call `list_tool_keys` with this app's `app_id` to get the exact valid keys, including this app's custom ones. | | enabled | boolean | No | Whether the tool is enabled. Optional; if omitted, the existing enabled state is preserved. | | description | string | No | Custom description shown to the LLM when the tool is registered. Pass `null` to clear and revert to the platform default. Omit to leave unchanged. | --- ### list_tool_keys List every valid `tool_key` for an app: built-in tools, hosted-integration tools, custom component tools (`render_*`), custom action tools, and MCP integration tools. **Scope:** `apps:read`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### get_default_capabilities Get the canonical platform-default state for capabilities, settings, and tool overrides. Takes no parameters. **Scope:** `apps:read`. **Chipp MCP:** [`app-settings`](/docs/guides/mcp/sub-mcps) No parameters. --- ## Knowledge Sources Manage RAG (Retrieval-Augmented Generation) knowledge bases. ### list_knowledge_sources List all knowledge sources for an application. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | status | string | No | Filter by status: pending, processing, completed, failed (optional) | | type | string | No | Filter by type: url, file, text, youtube, youtube_channel, sitemap, confluence (optional) | | limit | number | No | Max results (default 50) | | offset | number | No | Pagination offset (default 0) | --- ### get_knowledge_source Get details about a specific knowledge source. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The 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`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | url | string | Yes | The URL to crawl and index | | name | string | No | Display name for this source (optional, defaults to URL) | | crawl_links | boolean | No | Whether to follow and crawl linked pages (default: false). When true, crawls child pages up to max_depth levels deep. | | max_depth | number | No | How many levels deep to crawl linked pages (1-3, default: 1, capped at your plan's crawl depth). Only applies when crawl_links is true. | | max_pages | number | No | Maximum number of pages to crawl (default: 10, capped at your plan's crawl page limit). Only applies when crawl_links is true. | > **Note:** **Smart Detection:** YouTube URLs extract transcripts, social media extracts content, regular URLs are crawled. **Example:** ``` "Add https://docs.example.com to my FAQ app and crawl 3 levels deep" "Add this YouTube video to my training bot's knowledge base" ``` --- ### add_text_source Add raw text content as a knowledge source. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | name | string | Yes | Display name for this source | | content | string | Yes | The text content to index. Can be plain text, markdown, or Q&A format. | **Example:** ``` "Add this FAQ text to my support bot's knowledge base" ``` --- ### delete_knowledge_source Remove a knowledge source from an application. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID to delete | --- ### refresh_knowledge_source Re-crawl or re-process a knowledge source to update its content. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID to refresh | --- ### list_active_crawls List knowledge sources currently being processed or queued for an app. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application 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`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID whose crawl should be cancelled | The source status is set to `failed`. Jobs that are 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. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | files | object[] | Yes | Array of files to upload Fields: `fileName`, `content`. | 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`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID to check progress for | --- ### link_knowledge_source Link a knowledge source from one app to another, sharing its RAG data without duplicating it. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID to link | | target_app_id | string | Yes | The application ID to link the source to | --- ### unlink_knowledge_source Remove a linked knowledge source from an app. Does not delete the original source. **Scope:** `knowledge:write`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_id | string | Yes | The knowledge source ID to unlink | | app_id | string | Yes | The application ID to unlink the source from | --- ### list_linked_knowledge_sources List knowledge sources linked to an app from other apps (shared sources). **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ## Enterprise KB Evidence Read-only evidence retrieval over the org/workspace-scoped enterprise knowledge base. Authorization is resolved live on every call, so a revoked grant or a narrowed sharing scope takes effect immediately. Denials are uniform: a source that does not exist and one you are not authorized for return the same response, so nothing leaks about the wider corpus. These are distinct from the [Knowledge Sources](#knowledge-sources) tools above, which manage an app's OWN sources. Here `app_id` names the app acting as the retrieval caller, and you must already have access to it. ### discover_kb_capabilities List which org/workspace-scoped KB sources this app is currently granted access to. Always live, never a cached snapshot. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID acting as the retrieval caller | --- ### search_kb_evidence Run a bounded, paginated hybrid search (vector similarity + BM25 + document boosting) across the granted KB sources. Every hit carries a citation (source id + chunk anchor) that `get_kb_cited_chunk` resolves to exact content. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID acting as the retrieval caller | | query | string | Yes | The search query text | | page | number | No | Page number, 1-based (default 1) | | page_size | number | No | Results per page (default 10, max 25) | --- ### get_kb_source_metadata Get sanitized metadata (display name, sanitized url, type, sharing scope) for one granted source. Storage credentials and signed URLs are never returned. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID acting as the retrieval caller | | source_id | string | Yes | The knowledge source ID | --- ### get_kb_cited_chunk Resolve one search citation to its exact chunk content. Authorization is re-checked at read time, so a chunk cited by an earlier search is denied if the grant has since been revoked. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID acting as the retrieval caller | | chunk_id | string | Yes | The numeric chunk anchor from a search hit's citation (not a UUID) | --- ### read_kb_full_document Read the full content of one granted source. Gated by the same policy as search and metadata; there is no separate, weaker full-document grant. **Scope:** `knowledge:read`. **Chipp MCP:** [`knowledge`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID acting as the retrieval caller | | source_id | string | Yes | The knowledge source ID to read in full | --- ## Analytics Access usage data, conversations, and metrics. Access usage data, conversations, and metrics. ### get_app_analytics Get summary analytics for an application: total sessions, messages, unique users, and date range stats. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date string to filter from (optional, 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`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | query | string | No | Text to search for in messages (optional) | | since | string | No | ISO date to filter from (optional) | | limit | number | No | Max results (default 20) | | offset | number | No | Pagination offset (default 0) | **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`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | Yes | The chat session ID | --- ### get_top_queries Get the most common user queries. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | limit | number | No | Max results (default 20) | | since | string | No | ISO date to filter from (optional) | --- ### get_model_usage Get LLM model usage breakdown (token counts by model) for an app. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, defaults to 30 days) | --- ### get_response_time_analytics Get response time statistics based on message timestamps. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, defaults to 7 days) | **Returns:** Total responses, avg response ms, p50, p95. --- ### diagnose_chat_latency Explain why an app's chats are slow. Reads the per-turn latency records: how long users wait for the first sign of activity and for the first words (median and p90), the share of slow chats, the main causes with their evidence numbers, suggestions with the expected time saved, and the most recent slow turns. Causes marked platform-owned are Chipp's to fix. Contains only timings, sizes and ids, never message content. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | days | number | No | Look-back window in days: 1, 7, 30 or 90 (default 7; other values round up). | **Returns:** First-activity and first-text times, slow-chat share, causes with evidence, suggestions, recent slow turns. --- ### get_user_engagement Get user engagement metrics: sessions per user, messages per session, return rate. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, defaults to 30 days) | --- ### search_messages Search for specific text within messages across all conversations in an app. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | query | string | Yes | Text to search for in message content | | role | string | No | Filter by message role: user, assistant, or system (optional) | | since | string | No | ISO date to filter from (optional) | | 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 app's knowledge base (RAG chunks). **Scope:** `knowledge:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application 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. --- ### get_tag_analytics Get tag usage statistics for an app over a time period. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, 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 app: upload counts and total storage by MIME type. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, 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`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | No | ISO date to filter from (optional, 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 apps in your organization, ranked by session count and unique users. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | since | string | No | ISO date to filter from (optional, defaults to last 30 days) | | limit | number | No | Max results (default 10) | --- ### export_conversations Export conversations as JSON for an app within a date range. **Scope:** `analytics:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | since | string | Yes | ISO date to export from (required) | | until | string | No | ISO date to export until (optional, 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 application. **Scope:** `apps:read`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### get_tag Get details for a specific tag including utterances. **Scope:** `apps:read`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | --- ### create_tag Create a new intent tag. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | name | string | Yes | Tag name | | color | string | Yes | Tag color hex (e.g. #ef4444) | | description | string | No | Definition of when this tag should trigger. Jev classifies new tags from the name and this text, so be specific (recommended). | | static_text | string | No | Static text to respond with when this tag triggers (optional) | | similarity_threshold | number | No | Cosine similarity threshold 0-1 (default 0.8). Applies only to legacy embedding_v1 tags and the embedding fallback. | | jev_threshold | number | No | Jev match probability threshold 0-1 for jev_v1 tags (optional, default 0.5). | | freeze_conversation | boolean | No | Whether to freeze the conversation when this tag triggers (default false) | | notification_enabled | boolean | No | Whether to send notifications (default false) | | notification_email | string | No | Email to send notifications to (optional) | | webhook_url | string | No | Webhook URL to call when tag triggers (optional) | | positive_examples | string[] | No | Example utterances that SHOULD trigger this tag. Embedded server-side within this same call (the same pipeline the builder UI uses). For a jev_v1 tag they are boundary examples for Jev and the embedding fallback when Jev is unavailable; the tag matches without them. Optional. | | negative_examples | string[] | No | Counter-example utterances that must NOT trigger this tag, embedded alongside the positives. Optional. | **Actions when the tag matches:** - `static_text`: Replace AI response with fixed text - `freeze_conversation`: Stop conversation flow - `notification_enabled` with `notification_email` or `webhook_url`: Send an email or webhook alert **Example:** ``` "Create a tag called 'pricing' for my sales bot with examples like 'how much does it cost'" ``` --- ### update_tag Update an existing tag. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | name | string | No | New name (optional) | | color | string | No | New color (optional) | | description | string | No | New description (optional) | | static_text | string | No | New static text (optional) | | similarity_threshold | number | No | New similarity threshold for embedding_v1 tags (optional) | | jev_threshold | number | No | New Jev probability threshold 0-1 for jev_v1 tags; null resets to the default 0.5 (optional) | | enabled | boolean | No | Enable/disable (optional) | | freeze_conversation | boolean | No | Freeze on trigger (optional) | | notification_enabled | boolean | No | Enable notifications (optional) | | notification_email | string | No | Notification email (optional) | | webhook_url | string | No | Webhook URL (optional) | | positive_examples | string[] | No | Additional example utterances that SHOULD trigger this tag. APPENDED to any existing positive examples (deduped) and embedded server-side within this call -- never replaces the existing set. Use `set_tag_examples` to replace the set instead. Optional. | | negative_examples | string[] | No | Additional counter-example utterances that must NOT trigger this tag. APPENDED to any existing negative examples (deduped) and embedded server-side within this call. Optional. | --- ### delete_tag Delete a tag. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID to delete | --- ### list_tag_instances List messages that matched a specific tag. **Scope:** `analytics:read`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application 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`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_instance_id | string | Yes | The tag instance ID to remove | --- ### generate_utterances Generate training utterances for a tag using AI. Utterances are example phrases that should trigger the tag, and more utterances means better detection accuracy. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_name | string | Yes | The tag name (e.g. 'wants to cancel', 'billing question') | | 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 'pricing question' that detects when users ask about cost" ``` --- ### set_tag_examples Replace a tag's positive and/or negative example utterances without touching its other config. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | positive_examples | string[] | No | Full replacement set of positive examples. Omit to leave unchanged; pass [] to clear. | | negative_examples | string[] | No | Full replacement set of negative examples. Omit to leave unchanged; pass [] to clear. | --- ### add_tag_examples Append positive and/or negative example utterances to an existing tag without touching its other config. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | positive_examples | string[] | No | Positive examples to append (optional). | | negative_examples | string[] | No | Negative examples to append (optional). | --- ## Tag Examples Fine-grained management of individual training utterances (examples) attached to a tag. For whole-set replace/append operations, see [set_tag_examples](#set_tag_examples) and [add_tag_examples](#add_tag_examples). ### list_tag_examples List positive and negative examples (training utterances) for a tag. **Scope:** `apps:read`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | type | `"positive"` or `"negative"` | No | Filter to a single polarity (optional; returns both when omitted) | | format | `"json"` or `"csv"` | No | 'json' (default) returns the rows. 'csv' returns the same rows as a CSV string in `csv` (every cell quoted, formula characters defanged). | --- ### create_tag_examples Create (attach) one or more examples for a tag, all sharing the same polarity. Duplicate text for the tag is skipped and counted, not errored. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID to attach examples to | | examples | string[] | Yes | Example phrases to add (1-50) | | type | `"positive"` or `"negative"` | No | Polarity for all examples in this call (default 'positive') | --- ### update_tag_example Update an existing tag example's text and/or polarity. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | example_id | string | Yes | The example (utterance) ID to update | | utterance | string | No | New example text (optional) | | type | `"positive"` or `"negative"` | No | New polarity (optional) | --- ### delete_tag_example Delete (detach) a tag example. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID | | example_id | string | Yes | The example (utterance) ID to delete | --- ### import_tag_examples Bulk-import tag examples from CSV or JSONL. CSV needs a header row with a required `utterance` column plus optional `type` (`positive`\|`negative`, default positive) and `source` columns. JSONL is one JSON object per line: `{utterance, type?, source?}`. Duplicate text (either polarity) is skipped and counted, not errored. **Scope:** `apps:write`. **Chipp MCP:** [`tags`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tag_id | string | Yes | The tag ID to import examples into | | format | `"csv"` or `"jsonl"` | Yes | The payload format | | content | string | Yes | The raw CSV or JSONL text to import (up to 500 example rows) | --- ## Evaluations Create and run quality tests for your applications. ### list_evals List all evaluations for an application. **Scope:** `apps:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### get_eval Get details for a specific evaluation. **Scope:** `apps:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eval_id | string | Yes | The evaluation ID (from list_evals) | --- ### create_eval Create a new evaluation with test cases for an app. **Scope:** `apps:write`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | name | string | Yes | Evaluation name | | test_cases | object[] | Yes | Array of test case objects. Single-turn: {input, expected_output}. Scripted per-turn conversation: {turns, tag?}: an ordered array of {role, content, expected_response} turns replayed through the app's real chat pipeline, each user turn scored independently against its own expected_response (strict superset of single-turn: a 1-turn `turns` array is equivalent to input/expected_output). Older multi-turn scripted conversation: {user_turns, expected_output, per_turn_criteria?}: the app generates each intervening assistant turn and the case is judged as ONE conversation. At most one of turns / user_turns / persona_prompt may be set per case. Fields: `input`, `expected_output`, `turns`, `tag`, `user_turns`, `per_turn_criteria`, `persona_prompt`, `max_turns`. | | evaluation_method | string | No | Evaluation method: factuality, faithfulness, answer_relevancy, context_relevancy, or comprehensive (default: factuality) | | publish_gate | boolean | No | If true, publishing the app is blocked when this suite has never run or scored below publish_pass_threshold | | publish_pass_threshold | number | No | Score percentage (0-100) required to pass the publish gate (default: 100). Only used when publish_gate is true. | | run_on_publish | boolean | No | If true, automatically enqueue this eval suite as a background job after every successful publish | | webhook_url | string | No | HTTPS URL to receive a signed POST when an eval run completes or fails. Set to null to clear. | | webhook_signing_secret | string | No | Secret used to sign the webhook payload (HMAC-SHA256, X-Chipp-Signature header). Set to null to clear. | **Test case format:** ```json { "input": "What are your hours?", "expected_output": "We're open 9-5 Monday through Friday" } ``` --- ### update_eval Update an existing evaluation's name, test cases, or method. **Scope:** `apps:write`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eval_id | string | Yes | The evaluation ID | | name | string | No | New name (optional) | | test_cases | array | No | New test cases, FULL REPLACEMENT (optional). Single-turn: {input, expected_output}. Scripted per-turn conversation: {turns: [{role, content, expectedResponse?}], tag?}. See create_eval's test_cases schema for the full shape. Older multi-turn scripted conversation: {user_turns: string[], expected_output (conversation-level criteria), per_turn_criteria?}. | | evaluation_method | string | No | New evaluation method (optional) | | publish_gate | boolean | No | Block publish when this suite has never run or scores below publish_pass_threshold | | publish_pass_threshold | number | No | Score percentage (0-100) required to pass the publish gate (default: 100) | | run_on_publish | boolean | No | Automatically enqueue this suite as a background job after every successful publish | | webhook_url | string | No | HTTPS URL to POST when an eval run completes or fails. Null to clear. | | webhook_signing_secret | string | No | Secret used to sign webhook payloads (HMAC-SHA256). Null to clear. | --- ### delete_eval Delete an evaluation. **Scope:** `apps:write`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eval_id | string | Yes | The evaluation ID to delete | --- ### run_eval Run an evaluation against the app to score its responses on the test cases. **Scope:** `apps:write`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eval_id | string | Yes | The evaluation ID to run | | tag | `"smoke"` or `"regression"` or `"integration"` | No | Only run test cases carrying this tag | --- ### list_eval_results List past evaluation runs. **Scope:** `apps:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eval_id | string | Yes | The evaluation ID | | limit | number | No | Max results (default 20) | --- ### get_eval_result Get detailed results from a specific evaluation run. **Scope:** `apps:read`. **Chipp MCP:** [`analytics`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | result_id | string | Yes | The evaluation run ID | --- ## Custom Actions Manage API integrations for your applications. ### list_custom_actions List all custom actions for an application. **Scope:** `actions:read`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### get_custom_action Get the full current row of a custom action: url, method, `headers`, `query_params`, `body_params`, `path_params`, variables and `auth`, plus a `hint`. **Scope:** `actions:read`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action_id | string | Yes | The custom action ID (from get_app_actions / list_custom_actions) | The arrays use the names `update_custom_action` takes, so you can pass them back unchanged. --- ### create_custom_action Create a new API integration. **Scope:** `actions:write`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | name | string | Yes | Action name (used as the tool name for the LLM) | | description | string | Yes | Description of what this action does | | url | string | Yes | The HTTP endpoint URL. Use {name} placeholders for path parameters. | | method | `"GET"` or `"POST"` or `"PUT"` or `"DELETE"` or `"PATCH"` | Yes | HTTP method | | headers | array | No | Request headers as array of {key, value} objects (optional) | | path_params | array | No | Path parameters as array of {name, description, required} objects (optional). Each name must match a {name} placeholder in the URL (e.g. url 'https://api.example.com/users/{userId}/orders/{orderId}' with path_params [{name: 'userId', ...}, {name: 'orderId', ...}]). The value is supplied by the model at execution time and URL-encoded into the placeholder -- this is a distinct source from an Application Variable or a system variable, and does NOT require creating one. | | query_params | array | No | Query parameters as array of {name, type, description, required} objects (optional). Each entry may also carry "schema" (Optional structured schema for this parameter's value (JSON-Schema subset, enforced before the request runs and before any approval card). Arrays: items, minItems, maxItems; objects: properties, required, additionalProperties (true/false); strings: enum, pattern, minLength, maxLength; numbers/integers: minimum, maximum. Nested nodes need a type. Example for an array of orders: {"items": {"type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"], "additionalProperties": false}, "minItems": 1, "maxItems": 50}. Always give an array param an items schema.) and "dryRunIsReadOnly" (Only for a boolean AI-supplied parameter named exactly "dryRun": true declares that dryRun=true calls are a read-only preview, so they run without a human approval card even when the action requires approval. Default false.) | | body_params | array | No | Body parameters as array of {name, type, description, required} objects (optional). Each entry may also carry "schema" (Optional structured schema for this parameter's value (JSON-Schema subset, enforced before the request runs and before any approval card). Arrays: items, minItems, maxItems; objects: properties, required, additionalProperties (true/false); strings: enum, pattern, minLength, maxLength; numbers/integers: minimum, maximum. Nested nodes need a type. Example for an array of orders: {"items": {"type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"], "additionalProperties": false}, "minItems": 1, "maxItems": 50}. Always give an array param an items schema.) and "dryRunIsReadOnly" (Only for a boolean AI-supplied parameter named exactly "dryRun": true declares that dryRun=true calls are a read-only preview, so they run without a human approval card even when the action requires approval. Default false.) | | auth | object | No | Authentication for the action. Credentials are referenced by Application Variable name (create them first with create_app_variable, type='secret'); never inline a secret here. Fields: `type`, `source`, `variableName`, `aiParamKey`, `aiParamDescription`, `headerName`, `valuePrefix`, `basicUsername`, `tokenUrl`, `clientIdVariableName`, `clientSecretVariableName`, `scope`, `clientAuthMethod`, `certificateVariableName`, `privateKeyVariableName`, `assertionAudience`, `assertionAlgorithm`. | > **Note:** Custom actions have complex schemas. See the [Custom Actions Guide](/docs/custom-actions/overview) for detailed examples. --- ### update_custom_action Update an existing custom action. **Scope:** `actions:write`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action_id | string | Yes | The custom action ID (from get_app_actions / list_custom_actions) | | name | string | No | Name | | description | string | No | Description | | url | string | No | Endpoint URL (absolute https://) | | method | `"GET"` or `"POST"` or `"PUT"` or `"PATCH"` or `"DELETE"` | No | HTTP method | | headers | array | No | Headers ({name, value}). FULL REPLACEMENT: send every entry to keep, as read_custom_action / get_custom_action returned it. | | query_params | array | No | Query params ({name, description, type, required}). FULL REPLACEMENT: send every entry to keep, as read_custom_action / get_custom_action returned it. Each entry may also carry "schema" (Optional structured schema for this parameter's value (JSON-Schema subset, enforced before the request runs and before any approval card). Arrays: items, minItems, maxItems; objects: properties, required, additionalProperties (true/false); strings: enum, pattern, minLength, maxLength; numbers/integers: minimum, maximum. Nested nodes need a type. Example for an array of orders: {"items": {"type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"], "additionalProperties": false}, "minItems": 1, "maxItems": 50}. Always give an array param an items schema.) and "dryRunIsReadOnly" (Only for a boolean AI-supplied parameter named exactly "dryRun": true declares that dryRun=true calls are a read-only preview, so they run without a human approval card even when the action requires approval. Default false.) | | body_params | array | No | Body params ({name, description, type, required}). FULL REPLACEMENT: send every entry to keep, as read_custom_action / get_custom_action returned it. Each entry may also carry "schema" (Optional structured schema for this parameter's value (JSON-Schema subset, enforced before the request runs and before any approval card). Arrays: items, minItems, maxItems; objects: properties, required, additionalProperties (true/false); strings: enum, pattern, minLength, maxLength; numbers/integers: minimum, maximum. Nested nodes need a type. Example for an array of orders: {"items": {"type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"], "additionalProperties": false}, "minItems": 1, "maxItems": 50}. Always give an array param an items schema.) and "dryRunIsReadOnly" (Only for a boolean AI-supplied parameter named exactly "dryRun": true declares that dryRun=true calls are a read-only preview, so they run without a human approval card even when the action requires approval. Default false.) | | path_params | array | No | Path params ({name, description, required}); each name matches a {name} placeholder in the url. FULL REPLACEMENT: send every entry to keep, as read_custom_action / get_custom_action returned it. | | auth | object | No | Authentication for the action. Credentials are referenced by Application Variable name (create them first with create_app_variable, type='secret'); never inline a secret here. Omit to keep it; send to replace it entirely; null clears it. Fields: `type`, `source`, `variableName`, `aiParamKey`, `aiParamDescription`, `headerName`, `valuePrefix`, `basicUsername`, `tokenUrl`, `clientIdVariableName`, `clientSecretVariableName`, `scope`, `clientAuthMethod`, `certificateVariableName`, `privateKeyVariableName`, `assertionAudience`, `assertionAlgorithm`. | | reasoning | string | No | Brief explanation | It also needs write access to Custom Actions in the app's workspace. `headers` and the three params arrays replace the stored lists: call `get_custom_action` first and send back every entry you want to keep. A URL that belongs to a first-party hosted integration is refused with a hint to connect that integration instead. Returns the updated action with `success`, the `updated` field list and a `message`. --- ### delete_custom_action Delete a custom action. **Scope:** `actions:write`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action_id | string | Yes | The custom action ID to delete | --- ### test_custom_action Test a custom action by executing it with sample parameters. **Scope:** `actions:write`. **Chipp MCP:** [`actions`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action_id | string | Yes | The custom action ID to test | | parameters | object | No | Parameter values to send with the test request (optional) | | external_id | string | No | Optional value to simulate {{system.external_id}} for this test call. Omit to test as an anonymous session -- an action that references {{system.external_id}} will then be blocked with a field-specific notice instead of silently sending an empty value. | --- ## MCP Integrations Connect external MCP servers to your applications. ### list_mcp_integrations List all connected MCP servers for an application. **Scope:** `actions:read`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | --- ### get_mcp_integration Get details about a connected MCP server. **Scope:** `actions:read`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | integration_id | string | Yes | The integration ID | | app_id | string | Yes | The application ID | --- ### connect_mcp_server Connect an external MCP server to an application. **Scope:** `actions:write`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | | server_url | string | Yes | The MCP server URL (must be HTTPS) | | name | string | No | Display name for this integration (optional) | | auth_type | string | No | Authentication type: NONE, BEARER, or OAUTH (default: NONE) | | auth_token | string | No | Bearer token for authentication (if auth_type is BEARER) | --- ### update_mcp_integration_tools Enable or disable the entire MCP integration, or toggle specific tools by name. **Scope:** `actions:write`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | integration_id | string | Yes | The integration ID | | app_id | string | Yes | The application ID | | is_active | boolean | No | Enable or disable the entire integration (optional) | | enabled_tools | string[] | No | List of tool names to enable. Tools not in this list will be disabled. Use list_mcp_integrations or get_mcp_integration to see available tool names. (optional) | --- ### disconnect_mcp_server Remove an MCP server connection. **Scope:** `actions:write`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | integration_id | string | Yes | The integration ID to disconnect | | app_id | string | Yes | The application ID | --- ### list_hosted_integrations List hosted integration providers connected to an app (Google Drive, Gmail, Outlook, OneDrive, Slack, and others). **Scope:** `apps:read`. **Chipp MCP:** [`integrations`](/docs/guides/mcp/sub-mcps) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_id | string | Yes | The application ID | **Returns:** For each integration: `provider`, `label`, `is_active`, `account_email`, and `requires_consumer_auth`. --- ## Components Manage Component Studio custom UI components: HTML fragments (with embedded `