---
title: "Archestra MCP Server"
category: MCP
description: "Built-in MCP server providing tools for managing Archestra platform resources"
order: 5
lastUpdated: 2026-07-05
---
<!--
This file is auto-generated by `pnpm codegen:archestra-mcp-server-docs`.
Do not edit manually.
-->

The Archestra MCP Server is a built-in MCP server that ships with the platform and requires no installation. It exposes tools for managing platform resources such as agents, MCP servers, policies, and limits.

Most tools require explicit assignment to Agents or MCP Gateways before they can be used. The following tools are pre-installed on all new agents by default: [`todo_write`](#todo_write).

Additionally, [`query_knowledge_sources`](#query_knowledge_sources) is automatically assigned to Agents and MCP Gateways that have at least one [knowledge base or connector](/docs/platform-knowledge) attached. To use it, the user must have `knowledgeSource:query`.

All Archestra tools are prefixed with `archestra__`. Most built-in tools are always trusted — they bypass tool invocation and trusted data policies.

[`query_knowledge_sources`](#query_knowledge_sources) is an exception: its output is treated as sensitive by default and is evaluated by trusted data policies. See [AI Tool Guardrails](/docs/platform-ai-tool-guardrails) for more details.

## Auth

Archestra tools are **trusted** by default, meaning they bypass [tool invocation and trusted data policies](/docs/platform-ai-tool-guardrails) — the tool will always execute without policy evaluation.

[`query_knowledge_sources`](#query_knowledge_sources) is evaluated by trusted data policies and its results are treated as sensitive by default.

However, **RBAC (role-based access control) is still enforced**. Every tool is mapped to a required permission (resource + action). The `tools/list` endpoint dynamically filters tools so users only see tools they have permission to use. For example, a user without `knowledgeSource:create` permission will not see [`create_knowledge_base`](#create_knowledge_base) in their tool list and cannot execute it.

Some tools enforce an **additional access requirement** in their handler beyond this RBAC permission — for example, the team membership tools gate on `team:read` but then require the caller to be an organization-level team manager or an admin (team-member role) of the specific team. These tools are marked with a † in the tables below, and the requirement is spelled out in each tool's details.

## Tools Reference

### Identity

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `whoami` | Returns the name and ID of the current agent. | None (no additional RBAC permission required) |

#### whoami

Required RBAC permission: None (no additional RBAC permission required)

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | `string` | Yes | The ID of the current agent. |
| `agentName` | `string` | Yes | The display name of the current agent. |

### Agents

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `create_agent` | Create a new agent with the specified name, optional description, labels, prompts, icon emoji, explicit tool assignments, and sub-agent delegations. | `agent:create` |
| `get_agent` | Get a specific agent by ID or name. | `agent:read` |
| `list_agents` | List agents with optional filtering by name. | `agent:read` |
| `edit_agent` | Edit an existing agent. | `agent:update` |

#### create_agent

Required RBAC permission: `agent:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Name for the new resource. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided. |
| `labels` | `object[]` | No | Optional key-value labels for organization and categorization. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `teams` | `string[]` | No | Team IDs to attach when creating a team-scoped resource. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. Assigned skill discovery/loading tools (list_skills, load_skill), sandbox runtime tools (run_command, download_file, upload_file) — when the code runtime is enabled and assigned — persistent-files tools (search_files, read_file, save_file, edit_file, delete_file) — when the Projects feature is enabled and assigned — and app tools (scaffold_app, edit_app, read_app, render_app, list_apps) stay directly available in both modes. |
| `accessAllTools` | `boolean` | No | Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings. |
| `description` | `string \| null` | No | Optional human-readable description of the agent. |
| `icon` | `string \| null` | No | Optional emoji icon for the agent. |
| `knowledgeBaseIds` | `string[]` | No | Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name. |
| `connectorIds` | `string[]` | No | Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name. |
| `subAgentIds` | `string[]` | No | Agent IDs to delegate to from this newly created agent. |
| `suggestedPrompts` | `object[]` | No | Optional suggested prompts that appear in the chat UI. |
| `suggestedPrompts[].summaryTitle` | `string` | Yes | Short title shown to users for this suggested prompt. |
| `suggestedPrompts[].prompt` | `string` | Yes | Suggested prompt text users can click to start a conversation. |
| `systemPrompt` | `string \| null` | No | The system prompt that defines the agent's behavior. |
| `toolAssignments` | `object[]` | No | Explicit tool assignments to create immediately after the agent is created. |
| `toolAssignments[].toolId` | `string` | Yes | The ID of the tool to assign to the agent. |
| `toolAssignments[].resolveAtCallTime` | `boolean` | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. |
| `toolAssignments[].credentialResolutionMode` | `"static" \| "dynamic" \| "enterprise_managed"` | No |  |
| `toolAssignments[].mcpServerId` | `string \| null` | No | Optional MCP server installation to pin the tool to when using static credential resolution. |


#### get_agent

Required RBAC permission: `agent:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | The ID of the agent to fetch. Prefer the ID when you already have it. |
| `name` | `string` | No | The exact name of the agent to fetch when you do not already have the ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes | The resource ID. |
| `name` | `string` | Yes | The resource name. |
| `description` | `string \| null` | Yes | The resource description, if any. |
| `icon` | `string \| null` | Yes | The emoji icon, if configured. |
| `scope` | `"personal" \| "team" \| "org"` | Yes | The visibility scope. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | Yes | How tools are loaded for MCP clients and models. |
| `accessAllTools` | `boolean` | Yes | Whether search_tools/run_tool may dynamically access every tool the calling user can access. |
| `agentType` | `"agent" \| "llm_proxy" \| "mcp_gateway" \| "profile"` | Yes | The resource type. |
| `systemPrompt` | `string \| null` | No |  |
| `teams` | `object[]` | Yes | The teams attached to it. |
| `teams[].id` | `string` | Yes | The team ID. |
| `teams[].name` | `string` | Yes | The team name. |
| `labels` | `object[]` | Yes | Assigned labels. |
| `labels[].key` | `string` | Yes | The label key. |
| `labels[].value` | `string` | Yes | The label value. |
| `tools` | `object[]` | Yes | Assigned tools. |
| `tools[].id` | `string` | Yes | The assigned tool ID. |
| `tools[].name` | `string` | Yes | The tool name. |
| `tools[].description` | `string \| null` | Yes | The tool description, if any. |
| `tools[].catalogId` | `string \| null` | Yes | The MCP catalog ID the tool comes from, if any. |
| `knowledgeBaseIds` | `string[]` | Yes | Assigned knowledge base IDs. |
| `connectorIds` | `string[]` | Yes | Assigned knowledge connector IDs. |
| `suggestedPrompts` | `object[]` | Yes | Configured suggested prompts. |
| `suggestedPrompts[].summaryTitle` | `string` | Yes | The short title shown in the chat UI. |
| `suggestedPrompts[].prompt` | `string` | Yes | The suggested prompt text. |

#### list_agents

Required RBAC permission: `agent:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | `integer` | No | Maximum number of agents to return. |
| `name` | `string` | No | Optional agent name filter. Use this when the user names an agent but you still need to look up the ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `total` | `number` | Yes | The total number of matching agents. |
| `agents` | `object[]` | Yes |  |
| `agents[].id` | `string` | Yes | The agent ID. |
| `agents[].name` | `string` | Yes | The agent name. |
| `agents[].scope` | `"personal" \| "team" \| "org"` | Yes | The agent scope. |
| `agents[].description` | `string \| null` | Yes | The agent description, if any. |
| `agents[].teams` | `object[]` | Yes | Teams attached to it. |
| `agents[].teams[].id` | `string` | Yes | The team ID. |
| `agents[].teams[].name` | `string` | Yes | The team name. |
| `agents[].labels` | `object[]` | Yes | Assigned labels. |
| `agents[].labels[].key` | `string` | Yes | The label key. |
| `agents[].labels[].value` | `string` | Yes | The label value. |
| `agents[].tools` | `object[]` | Yes |  |
| `agents[].tools[].name` | `string` | Yes | The tool name. |
| `agents[].tools[].description` | `string \| null` | Yes | The tool description, if any. |
| `agents[].knowledgeSources` | `object[]` | Yes | Assigned knowledge bases and connectors. |
| `agents[].knowledgeSources[].name` | `string` | Yes | The knowledge source name. |
| `agents[].knowledgeSources[].description` | `string \| null` | Yes | The knowledge source description, if any. |
| `agents[].knowledgeSources[].type` | `"knowledge_base" \| "knowledge_connector"` | Yes | Whether this source is a knowledge base or connector. |

#### edit_agent

Required RBAC permission: `agent:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the agent to edit. Use get_agent or list_agents to look it up by name. |
| `subAgentIds` | `string[]` | No | Agent IDs to add as delegation targets. |
| `toolAssignments` | `object[]` | No | Explicit tool assignments to add or update on the agent. |
| `toolAssignments[].toolId` | `string` | Yes | The ID of the tool to assign to the agent. |
| `toolAssignments[].resolveAtCallTime` | `boolean` | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. |
| `toolAssignments[].credentialResolutionMode` | `"static" \| "dynamic" \| "enterprise_managed"` | No |  |
| `toolAssignments[].mcpServerId` | `string \| null` | No | Optional MCP server installation to pin the tool to when using static credential resolution. |
| `description` | `string \| null` | No | New description for the agent. |
| `icon` | `string \| null` | No | New emoji icon for the agent. |
| `knowledgeBaseIds` | `string[]` | No | Replace the agent's assigned knowledge bases with this set. |
| `labels` | `object[]` | No | Replace the agent's labels with this set. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `name` | `string` | No | New name for the agent. |
| `connectorIds` | `string[]` | No | Replace the agent's directly assigned knowledge connectors with this set. |
| `scope` | `"personal" \| "team" \| "org"` | No | Updated visibility scope for the agent. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. |
| `accessAllTools` | `boolean` | No | Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only'. |
| `suggestedPrompts` | `object[]` | No | Replace the agent's suggested prompts. |
| `suggestedPrompts[].summaryTitle` | `string` | Yes | Short title shown to users for this suggested prompt. |
| `suggestedPrompts[].prompt` | `string` | Yes | Suggested prompt text users can click to start a conversation. |
| `systemPrompt` | `string \| null` | No | New system prompt for the agent. |
| `teams` | `string[]` | No | Replace the teams attached to a team-scoped agent. |


### LLM Proxies

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `create_llm_proxy` | Create a new LLM proxy with the specified name and optional labels. | `llmProxy:create` |
| `get_llm_proxy` | Get a specific LLM proxy by ID or name. | `llmProxy:read` |
| `edit_llm_proxy` | Edit an existing LLM proxy. | `llmProxy:update` |

#### create_llm_proxy

Required RBAC permission: `llmProxy:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Name for the new resource. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided. |
| `labels` | `object[]` | No | Optional key-value labels for organization and categorization. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `teams` | `string[]` | No | Team IDs to attach when creating a team-scoped resource. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. Assigned skill discovery/loading tools (list_skills, load_skill), sandbox runtime tools (run_command, download_file, upload_file) — when the code runtime is enabled and assigned — persistent-files tools (search_files, read_file, save_file, edit_file, delete_file) — when the Projects feature is enabled and assigned — and app tools (scaffold_app, edit_app, read_app, render_app, list_apps) stay directly available in both modes. |
| `accessAllTools` | `boolean` | No | Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings. |


#### get_llm_proxy

Required RBAC permission: `llmProxy:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | The ID of the LLM proxy to fetch. Prefer the ID when you already have it. |
| `name` | `string` | No | The exact name of the LLM proxy to fetch when you do not already have the ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes | The resource ID. |
| `name` | `string` | Yes | The resource name. |
| `description` | `string \| null` | Yes | The resource description, if any. |
| `icon` | `string \| null` | Yes | The emoji icon, if configured. |
| `scope` | `"personal" \| "team" \| "org"` | Yes | The visibility scope. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | Yes | How tools are loaded for MCP clients and models. |
| `accessAllTools` | `boolean` | Yes | Whether search_tools/run_tool may dynamically access every tool the calling user can access. |
| `agentType` | `"agent" \| "llm_proxy" \| "mcp_gateway" \| "profile"` | Yes | The resource type. |
| `systemPrompt` | `string \| null` | No |  |
| `teams` | `object[]` | Yes | The teams attached to it. |
| `teams[].id` | `string` | Yes | The team ID. |
| `teams[].name` | `string` | Yes | The team name. |
| `labels` | `object[]` | Yes | Assigned labels. |
| `labels[].key` | `string` | Yes | The label key. |
| `labels[].value` | `string` | Yes | The label value. |
| `tools` | `object[]` | Yes | Assigned tools. |
| `tools[].id` | `string` | Yes | The assigned tool ID. |
| `tools[].name` | `string` | Yes | The tool name. |
| `tools[].description` | `string \| null` | Yes | The tool description, if any. |
| `tools[].catalogId` | `string \| null` | Yes | The MCP catalog ID the tool comes from, if any. |
| `knowledgeBaseIds` | `string[]` | Yes | Assigned knowledge base IDs. |
| `connectorIds` | `string[]` | Yes | Assigned knowledge connector IDs. |
| `suggestedPrompts` | `object[]` | Yes | Configured suggested prompts. |
| `suggestedPrompts[].summaryTitle` | `string` | Yes | The short title shown in the chat UI. |
| `suggestedPrompts[].prompt` | `string` | Yes | The suggested prompt text. |

#### edit_llm_proxy

Required RBAC permission: `llmProxy:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the LLM proxy to edit. Use get_llm_proxy to look it up by name first if needed. |
| `description` | `string \| null` | No | New description for the LLM proxy. |
| `icon` | `string \| null` | No | New emoji icon for the LLM proxy. |
| `labels` | `object[]` | No | Replace the LLM proxy's labels with this set. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `name` | `string` | No | New name for the LLM proxy. |
| `scope` | `"personal" \| "team" \| "org"` | No | Updated visibility scope for the LLM proxy. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. |
| `teams` | `string[]` | No | Replace the teams attached to a team-scoped LLM proxy. |


### MCP Gateways

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `create_mcp_gateway` | Create a new MCP gateway with the specified name, optional labels, and optional assigned knowledge bases or knowledge connectors. | `mcpGateway:create` |
| `get_mcp_gateway` | Get a specific MCP gateway by ID or name. | `mcpGateway:read` |
| `edit_mcp_gateway` | Edit an existing MCP gateway. | `mcpGateway:update` |

#### create_mcp_gateway

Required RBAC permission: `mcpGateway:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Name for the new resource. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided. |
| `labels` | `object[]` | No | Optional key-value labels for organization and categorization. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `teams` | `string[]` | No | Team IDs to attach when creating a team-scoped resource. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. |
| `accessAllTools` | `boolean` | No | Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings. |
| `knowledgeBaseIds` | `string[]` | No | Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name. |
| `connectorIds` | `string[]` | No | Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name. |


#### get_mcp_gateway

Required RBAC permission: `mcpGateway:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | The ID of the MCP gateway to fetch. Prefer the ID when you already have it. |
| `name` | `string` | No | The exact name of the MCP gateway to fetch when you do not already have the ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes | The resource ID. |
| `name` | `string` | Yes | The resource name. |
| `description` | `string \| null` | Yes | The resource description, if any. |
| `icon` | `string \| null` | Yes | The emoji icon, if configured. |
| `scope` | `"personal" \| "team" \| "org"` | Yes | The visibility scope. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | Yes | How tools are loaded for MCP clients and models. |
| `accessAllTools` | `boolean` | Yes | Whether search_tools/run_tool may dynamically access every tool the calling user can access. |
| `agentType` | `"agent" \| "llm_proxy" \| "mcp_gateway" \| "profile"` | Yes | The resource type. |
| `systemPrompt` | `string \| null` | No |  |
| `teams` | `object[]` | Yes | The teams attached to it. |
| `teams[].id` | `string` | Yes | The team ID. |
| `teams[].name` | `string` | Yes | The team name. |
| `labels` | `object[]` | Yes | Assigned labels. |
| `labels[].key` | `string` | Yes | The label key. |
| `labels[].value` | `string` | Yes | The label value. |
| `tools` | `object[]` | Yes | Assigned tools. |
| `tools[].id` | `string` | Yes | The assigned tool ID. |
| `tools[].name` | `string` | Yes | The tool name. |
| `tools[].description` | `string \| null` | Yes | The tool description, if any. |
| `tools[].catalogId` | `string \| null` | Yes | The MCP catalog ID the tool comes from, if any. |
| `knowledgeBaseIds` | `string[]` | Yes | Assigned knowledge base IDs. |
| `connectorIds` | `string[]` | Yes | Assigned knowledge connector IDs. |
| `suggestedPrompts` | `object[]` | Yes | Configured suggested prompts. |
| `suggestedPrompts[].summaryTitle` | `string` | Yes | The short title shown in the chat UI. |
| `suggestedPrompts[].prompt` | `string` | Yes | The suggested prompt text. |

#### edit_mcp_gateway

Required RBAC permission: `mcpGateway:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the MCP gateway to edit. Use get_mcp_gateway to look it up by name first if needed. |
| `description` | `string \| null` | No | New description for the MCP gateway. |
| `icon` | `string \| null` | No | New emoji icon for the MCP gateway. |
| `labels` | `object[]` | No | Replace the MCP gateway's labels with this set. |
| `labels[].key` | `string` | Yes |  |
| `labels[].value` | `string` | Yes |  |
| `name` | `string` | No | New name for the MCP gateway. |
| `scope` | `"personal" \| "team" \| "org"` | No | Updated visibility scope for the MCP gateway. |
| `toolExposureMode` | `"full" \| "search_and_run_only"` | No | How tools should be loaded for MCP clients and models. |
| `teams` | `string[]` | No | Replace the teams attached to a team-scoped MCP gateway. |
| `knowledgeBaseIds` | `string[]` | No | Replace the MCP gateway's assigned knowledge bases with this set. |
| `connectorIds` | `string[]` | No | Replace the MCP gateway's directly assigned knowledge connectors with this set. |


### MCP Servers

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `search_private_mcp_registry` | Search the private MCP registry for available MCP servers. | `mcpRegistry:read` |
| `get_mcp_servers` | List all MCP servers from the catalog. | `mcpRegistry:read` |
| `get_mcp_server_tools` | Get all tools available for a specific MCP server by its catalog ID (from get_mcp_servers). | `mcpRegistry:read` |
| `edit_mcp_description` | Edit an MCP server's display information and metadata. | `mcpRegistry:update` |
| `edit_mcp_config` | Edit an MCP server's technical configuration. | `mcpRegistry:update` |
| `create_mcp_server` | Create a new MCP server in the private registry. | `mcpRegistry:create` |
| `deploy_mcp_server` | Deploy (install) an MCP server from the catalog. | `mcpRegistry:update` |
| `list_mcp_server_deployments` | List all deployed (installed) MCP server instances accessible to the current user. | `mcpRegistry:read` |
| `get_mcp_server_logs` | Get recent container logs from a deployed local (K8s) MCP server. | `mcpRegistry:read` |
| `create_mcp_server_installation_request` | Allows users from within the Archestra Platform chat UI to submit a request for an MCP server to be added to their Archestra Platform's internal MCP server registry. | `mcpServerInstallationRequest:create` |

#### search_private_mcp_registry

Required RBAC permission: `mcpRegistry:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | `string` | No | Optional search query to filter MCP servers by name or description. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `items` | `object[]` | Yes | Catalog items matching the search. |
| `items[].id` | `string` | Yes | The catalog item ID. |
| `items[].name` | `string` | Yes | The MCP server name. |
| `items[].version` | `string \| null` | Yes | The version, if provided. |
| `items[].description` | `string \| null` | Yes | The server description, if any. |
| `items[].serverType` | `"local" \| "remote" \| "builtin" \| "app"` | Yes | Server type: local, remote, builtin, or app (user-generated App). |
| `items[].serverUrl` | `string \| null` | Yes | The remote server URL, if applicable. |
| `items[].repository` | `string \| null` | Yes | The repository URL, if available. |

#### get_mcp_servers

Required RBAC permission: `mcpRegistry:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `items` | `object[]` | Yes | Available MCP servers. |
| `items[].id` | `string` | Yes | The catalog item ID. |
| `items[].name` | `string` | Yes | The MCP server name. |
| `items[].icon` | `string \| null` | Yes | The emoji icon, if any. |
| `items[].description` | `string \| null` | Yes | The server description, if any. |
| `items[].scope` | `"personal" \| "team" \| "org"` | No | The visibility scope of the server. |
| `items[].teams` | `object[]` | Yes | Teams attached to a team-scoped server. |
| `items[].teams[].id` | `string` | Yes | The team ID. |
| `items[].teams[].name` | `string` | Yes | The team name. |

#### get_mcp_server_tools

Required RBAC permission: `mcpRegistry:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mcpServerId` | `string` | Yes | The catalog ID of the MCP server. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tools` | `object[]` | Yes | Tools exposed by the selected MCP server. |
| `tools[].id` | `string` | Yes | The tool ID. |
| `tools[].name` | `string` | Yes | The tool name. |
| `tools[].description` | `string \| null` | No | The tool description, if any. |
| `tools[].catalogId` | `string \| null` | No | The MCP catalog ID this tool belongs to. |

#### edit_mcp_description

Required RBAC permission: `mcpRegistry:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name. |
| `name` | `string` | No | Display name for the MCP server. |
| `description` | `string \| null` | No | Description of the MCP server. |
| `icon` | `string \| null` | No | Emoji icon for the MCP server. |
| `docsUrl` | `string \| null` | No | Documentation URL. |
| `repository` | `string \| null` | No | Source code repository URL. |
| `version` | `string \| null` | No | Version string. |
| `instructions` | `string \| null` | No | Setup or usage instructions. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope. |
| `labels` | `object[]` | No | Key-value labels for organization/categorization. |
| `labels[].key` | `string` | Yes | Label key. |
| `labels[].value` | `string` | Yes | Label value. |
| `teams` | `string[]` | No | Team IDs for team-scoped access control. |


#### edit_mcp_config

Required RBAC permission: `mcpRegistry:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name. |
| `serverType` | `"local" \| "remote" \| "builtin"` | No | Server type: local, remote, or builtin. |
| `serverUrl` | `string \| null` | No | [Remote] The URL of the remote MCP server. |
| `requiresAuth` | `boolean` | No | [Remote] Whether the server requires authentication. |
| `authDescription` | `string \| null` | No | [Remote] How to set up authentication. |
| `authFields` | `object[]` | No | [Remote] Authentication field definitions. |
| `authFields[].name` | `string` | Yes | Auth field name. |
| `authFields[].label` | `string` | Yes | Human-readable auth field label. |
| `authFields[].type` | `"header" \| "query" \| "cookie"` | Yes | Where to send this auth field. |
| `authFields[].secret` | `boolean` | Yes | Whether this field contains secret data. |
| `oauthConfig` | `object` | No | [Remote] OAuth configuration for the server. |
| `command` | `string` | No | [Local] Command to run (for example npx, uvx, or node). |
| `arguments` | `string[]` | No | [Local] Command-line arguments. |
| `environment` | `object[]` | No | [Local] Environment variables for the server process. |
| `environment[].key` | `string` | Yes | Environment variable name. |
| `environment[].type` | `"plain_text" \| "secret" \| "boolean" \| "number"` | Yes | Environment variable value type. |
| `environment[].value` | `string` | No | Literal environment variable value. |
| `environment[].promptOnInstallation` | `boolean` | Yes | Whether to prompt for this value during installation. |
| `environment[].required` | `boolean` | No | Whether the value is required. |
| `environment[].description` | `string` | No | Description shown to users. |
| `environment[].default` | `any` | No | Default value. |
| `environment[].mounted` | `boolean` | No | For secret values, mount as a file instead of an env var. |
| `envFrom` | `object[]` | No | [Local] Import env vars from Kubernetes Secrets or ConfigMaps. |
| `envFrom[].type` | `"secret" \| "configMap"` | Yes | Import source type. |
| `envFrom[].name` | `string` | Yes | Secret or ConfigMap name. |
| `envFrom[].prefix` | `string` | No | Optional environment variable prefix. |
| `dockerImage` | `string` | No | [Local] Custom Docker image. |
| `serviceAccount` | `string` | No | [Local] Kubernetes ServiceAccount name. |
| `transportType` | `"stdio" \| "streamable-http"` | No | [Local] Transport type. |
| `httpPort` | `number` | No | [Local] HTTP port for streamable-http transport. |
| `httpPath` | `string` | No | [Local] HTTP path for streamable-http transport. |
| `nodePort` | `number` | No | [Local] Kubernetes NodePort for local development. |
| `imagePullSecrets` | `object[]` | No | [Local] Image pull secrets for private registries. |
| `imagePullSecrets[].source` | `"existing"` | Yes | Image pull secret source. |
| `imagePullSecrets[].name` | `string` | Yes | Existing Kubernetes secret name. |
| `deploymentSpecYaml` | `string` | No | [Local] Custom Kubernetes deployment YAML override. |
| `installationCommand` | `string` | No | [Local] Command to install the MCP server package. |
| `userConfig` | `object` | No | User-configurable fields shown during installation. |


#### create_mcp_server

Required RBAC permission: `mcpRegistry:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Display name for the MCP server. |
| `description` | `string \| null` | No | Description of the MCP server. |
| `icon` | `string \| null` | No | Emoji icon for the MCP server. |
| `docsUrl` | `string \| null` | No | Documentation URL. |
| `repository` | `string \| null` | No | Source code repository URL. |
| `version` | `string \| null` | No | Version string. |
| `instructions` | `string \| null` | No | Setup or usage instructions. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope. |
| `labels` | `object[]` | No | Key-value labels for organization/categorization. |
| `labels[].key` | `string` | Yes | Label key. |
| `labels[].value` | `string` | Yes | Label value. |
| `teams` | `string[]` | No | Team IDs for team-scoped access control. |
| `environmentId` | `string \| null` | No | ID of the environment this server belongs to. Omit (or pass null) to leave it in the default environment. |
| `serverType` | `"local" \| "remote" \| "builtin"` | No | Server type: local, remote, or builtin. |
| `serverUrl` | `string \| null` | No | [Remote] The URL of the remote MCP server. |
| `requiresAuth` | `boolean` | No | [Remote] Whether the server requires authentication. |
| `authDescription` | `string \| null` | No | [Remote] How to set up authentication. |
| `authFields` | `object[]` | No | [Remote] Authentication field definitions. |
| `authFields[].name` | `string` | Yes | Auth field name. |
| `authFields[].label` | `string` | Yes | Human-readable auth field label. |
| `authFields[].type` | `"header" \| "query" \| "cookie"` | Yes | Where to send this auth field. |
| `authFields[].secret` | `boolean` | Yes | Whether this field contains secret data. |
| `oauthConfig` | `object` | No | [Remote] OAuth configuration for the server. |
| `command` | `string` | No | [Local] Command to run (for example npx, uvx, or node). |
| `arguments` | `string[]` | No | [Local] Command-line arguments. |
| `environment` | `object[]` | No | [Local] Environment variables for the server process. |
| `environment[].key` | `string` | Yes | Environment variable name. |
| `environment[].type` | `"plain_text" \| "secret" \| "boolean" \| "number"` | Yes | Environment variable value type. |
| `environment[].value` | `string` | No | Literal environment variable value. |
| `environment[].promptOnInstallation` | `boolean` | Yes | Whether to prompt for this value during installation. |
| `environment[].required` | `boolean` | No | Whether the value is required. |
| `environment[].description` | `string` | No | Description shown to users. |
| `environment[].default` | `any` | No | Default value. |
| `environment[].mounted` | `boolean` | No | For secret values, mount as a file instead of an env var. |
| `envFrom` | `object[]` | No | [Local] Import env vars from Kubernetes Secrets or ConfigMaps. |
| `envFrom[].type` | `"secret" \| "configMap"` | Yes | Import source type. |
| `envFrom[].name` | `string` | Yes | Secret or ConfigMap name. |
| `envFrom[].prefix` | `string` | No | Optional environment variable prefix. |
| `dockerImage` | `string` | No | [Local] Custom Docker image. |
| `serviceAccount` | `string` | No | [Local] Kubernetes ServiceAccount name. |
| `transportType` | `"stdio" \| "streamable-http"` | No | [Local] Transport type. |
| `httpPort` | `number` | No | [Local] HTTP port for streamable-http transport. |
| `httpPath` | `string` | No | [Local] HTTP path for streamable-http transport. |
| `nodePort` | `number` | No | [Local] Kubernetes NodePort for local development. |
| `imagePullSecrets` | `object[]` | No | [Local] Image pull secrets for private registries. |
| `imagePullSecrets[].source` | `"existing"` | Yes | Image pull secret source. |
| `imagePullSecrets[].name` | `string` | Yes | Existing Kubernetes secret name. |
| `deploymentSpecYaml` | `string` | No | [Local] Custom Kubernetes deployment YAML override. |
| `installationCommand` | `string` | No | [Local] Command to install the MCP server package. |
| `userConfig` | `object` | No | User-configurable fields shown during installation. |


#### deploy_mcp_server

Required RBAC permission: `mcpRegistry:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `catalogId` | `string` | Yes | The catalog ID of the MCP server to deploy. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope for the deployment: 'personal' (default), 'team' (requires teamId), or 'org' (admins only, visible to all org members). |
| `teamId` | `string` | No | Optional team ID for a team-scoped deployment (required when scope='team'). |
| `agentIds` | `string[]` | No | Optional agent IDs to assign the server's tools to after deployment. |


#### list_mcp_server_deployments

Required RBAC permission: `mcpRegistry:read`

This tool takes no arguments.


#### get_mcp_server_logs

Required RBAC permission: `mcpRegistry:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `serverId` | `string` | Yes | The deployment ID of the MCP server. |
| `lines` | `integer` | No | Number of log lines to retrieve. |


#### create_mcp_server_installation_request

Required RBAC permission: `mcpServerInstallationRequest:create`

This tool takes no arguments.


### Teams

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `create_team` | Create a new team in the organization. | `team:create` |
| `get_team` | Retrieve a single team by its ID or name, including its current member count. | `team:read` † |
| `list_teams` | List all teams in the organization, optionally filtered by a name substring. | `team:read` † |
| `edit_team` | Update a team's name and/or description. | `team:update` |
| `delete_team` | Delete a team by ID. | `team:delete` |
| `list_team_members` | List all members of a team along with their roles. | `team:read` † |
| `add_team_member` | Add an organization user to a team by user ID or email, optionally as an admin. | `team:read` † |
| `update_team_member_role` | Change a team member's role between admin and member. | `team:read` † |
| `remove_team_member` | Remove a member from a team. | `team:read` † |

† This tool enforces an additional access requirement beyond its RBAC permission — see its details below.

#### create_team

Required RBAC permission: `team:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the team. |
| `description` | `string` | No | Optional human-readable description of the team. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | `object` | Yes |  |
| `team.id` | `string` | Yes | The team ID. |
| `team.name` | `string` | Yes | The team name. |
| `team.description` | `string \| null` | Yes | The team description, if any. |
| `team.organizationId` | `string` | Yes | The organization the team belongs to. |
| `team.createdBy` | `string \| null` | Yes | The ID of the user who created the team. |
| `team.memberCount` | `number` | Yes | The number of members currently in the team. |
| `team.createdAt` | `string` | Yes | ISO timestamp when the team was created. |
| `team.updatedAt` | `string` | Yes | ISO timestamp when the team was last updated. |

#### get_team

Required RBAC permission: `team:read`

Additional access requirement: Callers without organization-level team management (`team:create`) can only read teams they are a member of.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | The ID of the team to fetch. |
| `name` | `string` | No | The name of the team to fetch (within the organization). |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | `object` | Yes |  |
| `team.id` | `string` | Yes | The team ID. |
| `team.name` | `string` | Yes | The team name. |
| `team.description` | `string \| null` | Yes | The team description, if any. |
| `team.organizationId` | `string` | Yes | The organization the team belongs to. |
| `team.createdBy` | `string \| null` | Yes | The ID of the user who created the team. |
| `team.memberCount` | `number` | Yes | The number of members currently in the team. |
| `team.createdAt` | `string` | Yes | ISO timestamp when the team was created. |
| `team.updatedAt` | `string` | Yes | ISO timestamp when the team was last updated. |

#### list_teams

Required RBAC permission: `team:read`

Additional access requirement: Callers without organization-level team management (`team:create`) only see teams they are a member of.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | No | Optional case-insensitive name substring to filter by. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `teams` | `object[]` | Yes |  |
| `teams[].id` | `string` | Yes | The team ID. |
| `teams[].name` | `string` | Yes | The team name. |
| `teams[].description` | `string \| null` | Yes | The team description, if any. |
| `teams[].organizationId` | `string` | Yes | The organization the team belongs to. |
| `teams[].createdBy` | `string \| null` | Yes | The ID of the user who created the team. |
| `teams[].memberCount` | `number` | Yes | The number of members currently in the team. |
| `teams[].createdAt` | `string` | Yes | ISO timestamp when the team was created. |
| `teams[].updatedAt` | `string` | Yes | ISO timestamp when the team was last updated. |

#### edit_team

Required RBAC permission: `team:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the team to update. |
| `name` | `string` | No | Optional new team name. |
| `description` | `string \| null` | No | Optional new team description. Pass null to clear an existing description. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | `object` | Yes |  |
| `team.id` | `string` | Yes | The team ID. |
| `team.name` | `string` | Yes | The team name. |
| `team.description` | `string \| null` | Yes | The team description, if any. |
| `team.organizationId` | `string` | Yes | The organization the team belongs to. |
| `team.createdBy` | `string \| null` | Yes | The ID of the user who created the team. |
| `team.memberCount` | `number` | Yes | The number of members currently in the team. |
| `team.createdAt` | `string` | Yes | ISO timestamp when the team was created. |
| `team.updatedAt` | `string` | Yes | ISO timestamp when the team was last updated. |

#### delete_team

Required RBAC permission: `team:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the team to delete. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes |  |
| `id` | `string` | Yes |  |

#### list_team_members

Required RBAC permission: `team:read`

Additional access requirement: Callers without organization-level team management (`team:create`) can only read members of teams they are a member of.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | `string` | Yes | The ID of the team whose members to list. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `members` | `object[]` | Yes |  |
| `members[].id` | `string` | Yes | The team membership row ID. |
| `members[].teamId` | `string` | Yes | The team the membership belongs to. |
| `members[].userId` | `string` | Yes | The ID of the member user. |
| `members[].role` | `"admin" \| "member"` | Yes | The member's role within the team (admin or member). |
| `members[].syncedFromSso` | `boolean` | Yes | Whether this membership is managed by SSO group sync. |
| `members[].name` | `string \| null` | No | The member's display name, when available. |
| `members[].email` | `string` | No | The member's email, when available. |
| `members[].createdAt` | `string` | Yes | ISO timestamp when the membership was created. |

#### add_team_member

Required RBAC permission: `team:read`

Additional access requirement: Beyond `team:read`, the caller must be an organization-level team manager (a role granting `team:create`) or an **admin** of the target team.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | `string` | Yes | The ID of the team to add the member to. |
| `user` | `string` | Yes | The user to add, identified by their user ID or email address. The user must already belong to the organization. |
| `role` | `"admin" \| "member"` | No | The role to assign within the team. Defaults to 'member'. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `member` | `object` | Yes |  |
| `member.id` | `string` | Yes | The team membership row ID. |
| `member.teamId` | `string` | Yes | The team the membership belongs to. |
| `member.userId` | `string` | Yes | The ID of the member user. |
| `member.role` | `"admin" \| "member"` | Yes | The member's role within the team (admin or member). |
| `member.syncedFromSso` | `boolean` | Yes | Whether this membership is managed by SSO group sync. |
| `member.name` | `string \| null` | No | The member's display name, when available. |
| `member.email` | `string` | No | The member's email, when available. |
| `member.createdAt` | `string` | Yes | ISO timestamp when the membership was created. |

#### update_team_member_role

Required RBAC permission: `team:read`

Additional access requirement: Beyond `team:read`, the caller must be an organization-level team manager (a role granting `team:create`) or an **admin** of the target team.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | `string` | Yes | The ID of the team. |
| `user_id` | `string` | Yes | The ID of the member user to update. |
| `role` | `"admin" \| "member"` | Yes | The new role for the member (admin or member). |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `member` | `object` | Yes |  |
| `member.id` | `string` | Yes | The team membership row ID. |
| `member.teamId` | `string` | Yes | The team the membership belongs to. |
| `member.userId` | `string` | Yes | The ID of the member user. |
| `member.role` | `"admin" \| "member"` | Yes | The member's role within the team (admin or member). |
| `member.syncedFromSso` | `boolean` | Yes | Whether this membership is managed by SSO group sync. |
| `member.name` | `string \| null` | No | The member's display name, when available. |
| `member.email` | `string` | No | The member's email, when available. |
| `member.createdAt` | `string` | Yes | ISO timestamp when the membership was created. |

#### remove_team_member

Required RBAC permission: `team:read`

Additional access requirement: Beyond `team:read`, the caller must be an organization-level team manager (a role granting `team:create`) or an **admin** of the target team.

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | `string` | Yes | The ID of the team. |
| `user_id` | `string` | Yes | The ID of the member user to remove from the team. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes |  |
| `teamId` | `string` | Yes |  |
| `userId` | `string` | Yes |  |

### Limits

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `create_limit` | Create a new cost or usage limit for an organization, team, agent, user, virtual key, environment, or MCP gateway. | `llmLimit:create` |
| `get_limits` | Retrieve all limits, optionally filtered by entity type and/or entity ID. | `llmLimit:read` |
| `update_limit` | Update mutable fields on an existing limit. | `llmLimit:update` |
| `delete_limit` | Delete an existing limit by ID. | `llmLimit:delete` |
| `get_agent_token_usage` | Get the total token usage (input and output) for a specific agent. | `llmLimit:read` |
| `get_llm_proxy_token_usage` | Get the total token usage (input and output) for a specific LLM proxy. | `llmLimit:read` |

#### create_limit

Required RBAC permission: `llmLimit:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_type` | `"organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment"` | Yes | The type of entity to apply the limit to. |
| `entity_id` | `string` | Yes | The ID of the entity (organization, team, agent, user, virtual_key, or environment). |
| `limit_type` | `"token_cost" \| "mcp_server_calls" \| "tool_calls"` | Yes | The type of limit to apply. |
| `limit_value` | `number` | Yes | The limit value (tokens or count depending on limit type). |
| `model` | `string[] \| null` | No | Array of model names. Omit for all models. |
| `cleanup_interval` | `"1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month"` | No | Optional cleanup interval for this limit. Omit to use the calendar-month default. |
| `mcp_server_name` | `string` | No | MCP server name. Required for mcp_server_calls and tool_calls limits. |
| `tool_name` | `string` | No | Tool name. Required for tool_calls limits. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | `object` | Yes |  |
| `limit.id` | `string` | Yes | The limit ID. |
| `limit.entityType` | `"organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment"` | Yes | The limited entity type. |
| `limit.entityId` | `string` | Yes | The limited entity ID. |
| `limit.limitType` | `"token_cost" \| "mcp_server_calls" \| "tool_calls"` | Yes | The kind of limit. |
| `limit.limitValue` | `number` | Yes | The configured limit value. |
| `limit.cleanupInterval` | `"1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month"` | Yes | How often this limit resets. |
| `limit.model` | `string[] \| null` | No | Models targeted by a token_cost limit. Null or empty array means all models. |
| `limit.mcpServerName` | `string \| null` | No | MCP server name for MCP-specific limits, if any. |
| `limit.toolName` | `string \| null` | No | Tool name for tool-specific limits, if any. |

#### get_limits

Required RBAC permission: `llmLimit:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_type` | `"organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment"` | No | Optional filter by entity type. |
| `entity_id` | `string` | No | Optional filter by entity ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limits` | `object[]` | Yes |  |
| `limits[].id` | `string` | Yes | The limit ID. |
| `limits[].entityType` | `"organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment"` | Yes | The limited entity type. |
| `limits[].entityId` | `string` | Yes | The limited entity ID. |
| `limits[].limitType` | `"token_cost" \| "mcp_server_calls" \| "tool_calls"` | Yes | The kind of limit. |
| `limits[].limitValue` | `number` | Yes | The configured limit value. |
| `limits[].cleanupInterval` | `"1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month"` | Yes | How often this limit resets. |
| `limits[].model` | `string[] \| null` | No | Models targeted by a token_cost limit. Null or empty array means all models. |
| `limits[].mcpServerName` | `string \| null` | No | MCP server name for MCP-specific limits, if any. |
| `limits[].toolName` | `string \| null` | No | Tool name for tool-specific limits, if any. |

#### update_limit

Required RBAC permission: `llmLimit:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the limit to update. |
| `limit_value` | `number` | No | Optional new limit value. |
| `cleanup_interval` | `"1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month"` | No | Optional new cleanup interval for this limit. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | `object` | Yes |  |
| `limit.id` | `string` | Yes | The limit ID. |
| `limit.entityType` | `"organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment"` | Yes | The limited entity type. |
| `limit.entityId` | `string` | Yes | The limited entity ID. |
| `limit.limitType` | `"token_cost" \| "mcp_server_calls" \| "tool_calls"` | Yes | The kind of limit. |
| `limit.limitValue` | `number` | Yes | The configured limit value. |
| `limit.cleanupInterval` | `"1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month"` | Yes | How often this limit resets. |
| `limit.model` | `string[] \| null` | No | Models targeted by a token_cost limit. Null or empty array means all models. |
| `limit.mcpServerName` | `string \| null` | No | MCP server name for MCP-specific limits, if any. |
| `limit.toolName` | `string \| null` | No | Tool name for tool-specific limits, if any. |

#### delete_limit

Required RBAC permission: `llmLimit:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the limit to delete. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes |  |
| `id` | `string` | Yes |  |

#### get_agent_token_usage

Required RBAC permission: `llmLimit:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | Optional agent ID. Defaults to the current agent. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `totalInputTokens` | `number` | Yes |  |
| `totalOutputTokens` | `number` | Yes |  |
| `totalTokens` | `number` | Yes |  |

#### get_llm_proxy_token_usage

Required RBAC permission: `llmLimit:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | No | Optional LLM proxy ID. Defaults to the current agent. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `totalInputTokens` | `number` | Yes |  |
| `totalOutputTokens` | `number` | Yes |  |
| `totalTokens` | `number` | Yes |  |

### Policies

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `get_autonomy_policy_operators` | Get all supported policy operators with their human-readable labels | `toolPolicy:read` |
| `get_tool_invocation_policies` | Get all tool invocation policies | `toolPolicy:read` |
| `create_tool_invocation_policy` | Create a new tool invocation policy | `toolPolicy:create` |
| `get_tool_invocation_policy` | Get a specific tool invocation policy by ID | `toolPolicy:read` |
| `update_tool_invocation_policy` | Update a tool invocation policy | `toolPolicy:update` |
| `delete_tool_invocation_policy` | Delete a tool invocation policy by ID | `toolPolicy:delete` |
| `get_trusted_data_policies` | Get all trusted data policies | `toolPolicy:read` |
| `create_trusted_data_policy` | Create a new trusted data policy | `toolPolicy:create` |
| `get_trusted_data_policy` | Get a specific trusted data policy by ID | `toolPolicy:read` |
| `update_trusted_data_policy` | Update a trusted data policy | `toolPolicy:update` |
| `delete_trusted_data_policy` | Delete a trusted data policy by ID | `toolPolicy:delete` |

#### get_autonomy_policy_operators

Required RBAC permission: `toolPolicy:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `operators` | `object[]` | Yes | Supported autonomy policy operators. |
| `operators[].value` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The operator enum value. |
| `operators[].label` | `string` | Yes | The human-readable label. |

#### get_tool_invocation_policies

Required RBAC permission: `toolPolicy:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policies` | `object[]` | Yes | Tool invocation policies. |
| `policies[].id` | `string` | Yes | The policy ID. |
| `policies[].toolId` | `string` | Yes | The tool ID this policy targets. |
| `policies[].conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policies[].conditions[].key` | `string` | Yes | The evaluated argument or context key. |
| `policies[].conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policies[].conditions[].value` | `string` | Yes | The comparison value. |
| `policies[].action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | Yes | The policy action. |
| `policies[].reason` | `string \| null` | Yes | The policy reason, if any. |

#### create_tool_invocation_policy

Required RBAC permission: `toolPolicy:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `toolId` | `string` | Yes | The ID of the tool (UUID from the tools table). |
| `conditions` | `object[]` | Yes | Array of conditions that must all match. Empty array means unconditional. |
| `conditions[].key` | `string` | Yes | The argument name or context path to evaluate (for example `url` or `context.externalAgentId`). |
| `conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `conditions[].value` | `string` | Yes | The value to compare against. |
| `action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | Yes | The action to take when the policy matches. |
| `reason` | `string` | No | Human-readable explanation for why this policy exists. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested tool invocation policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated argument or context key. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | Yes | The policy action. |
| `policy.reason` | `string \| null` | Yes | The policy reason, if any. |

#### get_tool_invocation_policy

Required RBAC permission: `toolPolicy:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the tool invocation policy. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested tool invocation policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated argument or context key. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | Yes | The policy action. |
| `policy.reason` | `string \| null` | Yes | The policy reason, if any. |

#### update_tool_invocation_policy

Required RBAC permission: `toolPolicy:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the tool invocation policy to update. |
| `toolId` | `string` | No | The ID of the tool (UUID from the tools table). |
| `conditions` | `object[]` | No | Updated array of conditions that must all match. Empty array means unconditional. |
| `conditions[].key` | `string` | Yes | The argument name or context path to evaluate (for example `url` or `context.externalAgentId`). |
| `conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `conditions[].value` | `string` | Yes | The value to compare against. |
| `action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | No | Updated action to take when the policy matches. |
| `reason` | `string \| null` | No | Updated human-readable explanation for why this policy exists. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested tool invocation policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated argument or context key. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"allow_when_context_is_untrusted" \| "block_when_context_is_untrusted" \| "block_always" \| "require_approval"` | Yes | The policy action. |
| `policy.reason` | `string \| null` | Yes | The policy reason, if any. |

#### delete_tool_invocation_policy

Required RBAC permission: `toolPolicy:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the tool invocation policy. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the delete succeeded. |

#### get_trusted_data_policies

Required RBAC permission: `toolPolicy:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policies` | `object[]` | Yes | Trusted data policies. |
| `policies[].id` | `string` | Yes | The policy ID. |
| `policies[].toolId` | `string` | Yes | The tool ID this policy targets. |
| `policies[].conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policies[].conditions[].key` | `string` | Yes | The evaluated result key or path. |
| `policies[].conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policies[].conditions[].value` | `string` | Yes | The comparison value. |
| `policies[].action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | Yes | The policy action. |
| `policies[].description` | `string \| null` | Yes | The policy description, if any. |

#### create_trusted_data_policy

Required RBAC permission: `toolPolicy:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `toolId` | `string` | Yes | The ID of the tool (UUID from the tools table). |
| `conditions` | `object[]` | Yes | Array of conditions that must all match. Empty array means unconditional. |
| `conditions[].key` | `string` | Yes | The attribute key or path in the tool result to evaluate (for example `emails[*].from` or `source`). |
| `conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `conditions[].value` | `string` | Yes | The value to compare against. |
| `action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | Yes | The action to take when the policy matches. |
| `description` | `string` | No | Human-readable explanation for why this policy exists. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested trusted data policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated result key or path. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | Yes | The policy action. |
| `policy.description` | `string \| null` | Yes | The policy description, if any. |

#### get_trusted_data_policy

Required RBAC permission: `toolPolicy:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the trusted data policy. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested trusted data policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated result key or path. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | Yes | The policy action. |
| `policy.description` | `string \| null` | Yes | The policy description, if any. |

#### update_trusted_data_policy

Required RBAC permission: `toolPolicy:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the trusted data policy to update. |
| `toolId` | `string` | No | The ID of the tool (UUID from the tools table). |
| `conditions` | `object[]` | No | Updated array of conditions that must all match. Empty array means unconditional. |
| `conditions[].key` | `string` | Yes | The attribute key or path in the tool result to evaluate (for example `emails[*].from` or `source`). |
| `conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `conditions[].value` | `string` | Yes | The value to compare against. |
| `action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | No | Updated action to take when the policy matches. |
| `description` | `string \| null` | No | Updated human-readable explanation for why this policy exists. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `policy` | `object` | Yes | The requested trusted data policy. |
| `policy.id` | `string` | Yes | The policy ID. |
| `policy.toolId` | `string` | Yes | The tool ID this policy targets. |
| `policy.conditions` | `object[]` | Yes | Conditions evaluated for the policy. |
| `policy.conditions[].key` | `string` | Yes | The evaluated result key or path. |
| `policy.conditions[].operator` | `"equal" \| "notEqual" \| "contains" \| "notContains" \| "startsWith" \| "endsWith" \| "regex"` | Yes | The comparison operator. |
| `policy.conditions[].value` | `string` | Yes | The comparison value. |
| `policy.action` | `"block_always" \| "mark_as_trusted" \| "mark_as_untrusted" \| "sanitize_with_dual_llm"` | Yes | The policy action. |
| `policy.description` | `string \| null` | Yes | The policy description, if any. |

#### delete_trusted_data_policy

Required RBAC permission: `toolPolicy:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | The ID of the trusted data policy. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the delete succeeded. |

### Tool Assignment

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `bulk_assign_tools_to_agents` | Assign multiple tools to multiple agents in bulk with validation and error handling | `agent:update` |
| `bulk_assign_tools_to_mcp_gateways` | Assign multiple tools to multiple MCP gateways in bulk with validation and error handling | `mcpGateway:update` |

#### bulk_assign_tools_to_agents

Required RBAC permission: `agent:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assignments` | `object[]` | Yes | Assignments to create or update for agents. |
| `assignments[].toolId` | `string` | Yes | The ID of the tool to assign. |
| `assignments[].resolveAtCallTime` | `boolean` | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. |
| `assignments[].credentialResolutionMode` | `"static" \| "dynamic" \| "enterprise_managed"` | No |  |
| `assignments[].mcpServerId` | `string \| null` | No | Optional MCP server installation to pin the tool to when using static credential resolution. |
| `assignments[].agentId` | `string` | Yes | The agent ID to assign the tool to. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `succeeded` | `object[]` | Yes | Assignments that succeeded. |
| `succeeded[].agentId` | `string` | Yes | The target agent ID. |
| `succeeded[].toolId` | `string` | Yes | The tool ID. |
| `succeeded[].error` | `string` | No | Validation or assignment error. |
| `succeeded[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `succeeded[].errorType` | `string` | No | Structured assignment error type. |
| `failed` | `object[]` | Yes | Assignments that failed. |
| `failed[].agentId` | `string` | Yes | The target agent ID. |
| `failed[].toolId` | `string` | Yes | The tool ID. |
| `failed[].error` | `string` | No | Validation or assignment error. |
| `failed[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `failed[].errorType` | `string` | No | Structured assignment error type. |
| `duplicates` | `object[]` | Yes | Assignments skipped because they already existed. |
| `duplicates[].agentId` | `string` | Yes | The target agent ID. |
| `duplicates[].toolId` | `string` | Yes | The tool ID. |
| `duplicates[].error` | `string` | No | Validation or assignment error. |
| `duplicates[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `duplicates[].errorType` | `string` | No | Structured assignment error type. |

#### bulk_assign_tools_to_mcp_gateways

Required RBAC permission: `mcpGateway:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assignments` | `object[]` | Yes | Assignments to create or update for MCP gateways. |
| `assignments[].toolId` | `string` | Yes | The ID of the tool to assign. |
| `assignments[].resolveAtCallTime` | `boolean` | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. |
| `assignments[].credentialResolutionMode` | `"static" \| "dynamic" \| "enterprise_managed"` | No |  |
| `assignments[].mcpServerId` | `string \| null` | No | Optional MCP server installation to pin the tool to when using static credential resolution. |
| `assignments[].mcpGatewayId` | `string` | Yes | The MCP gateway ID to assign the tool to. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `succeeded` | `object[]` | Yes | Assignments that succeeded. |
| `succeeded[].mcpGatewayId` | `string` | Yes | The target MCP gateway ID. |
| `succeeded[].toolId` | `string` | Yes | The tool ID. |
| `succeeded[].error` | `string` | No | Validation or assignment error. |
| `succeeded[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `succeeded[].errorType` | `string` | No | Structured assignment error type. |
| `failed` | `object[]` | Yes | Assignments that failed. |
| `failed[].mcpGatewayId` | `string` | Yes | The target MCP gateway ID. |
| `failed[].toolId` | `string` | Yes | The tool ID. |
| `failed[].error` | `string` | No | Validation or assignment error. |
| `failed[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `failed[].errorType` | `string` | No | Structured assignment error type. |
| `duplicates` | `object[]` | Yes | Assignments skipped because they already existed. |
| `duplicates[].mcpGatewayId` | `string` | Yes | The target MCP gateway ID. |
| `duplicates[].toolId` | `string` | Yes | The tool ID. |
| `duplicates[].error` | `string` | No | Validation or assignment error. |
| `duplicates[].errorCode` | `"not_found" \| "validation_error"` | No | Structured assignment error code. |
| `duplicates[].errorType` | `string` | No | Structured assignment error type. |

### Knowledge Management

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `query_knowledge_sources` | Query the organization's knowledge sources to retrieve relevant information. | `knowledgeSource:query` |
| `create_knowledge_base` | Create a new knowledge base for organizing knowledge connectors. | `knowledgeSource:create` |
| `get_knowledge_bases` | List all knowledge bases in the organization. | `knowledgeSource:read` |
| `get_knowledge_base` | Get details of a specific knowledge base by ID. | `knowledgeSource:read` |
| `update_knowledge_base` | Update an existing knowledge base. | `knowledgeSource:update` |
| `delete_knowledge_base` | Delete a knowledge base by ID. | `knowledgeSource:delete` |
| `create_knowledge_connector` | Create a new knowledge connector for ingesting data from external sources. | `knowledgeSource:create` |
| `get_knowledge_connectors` | List all knowledge connectors in the organization. | `knowledgeSource:read` |
| `get_knowledge_connector` | Get details of a specific knowledge connector by ID. | `knowledgeSource:read` |
| `update_knowledge_connector` | Update an existing knowledge connector. | `knowledgeSource:update` |
| `delete_knowledge_connector` | Delete a knowledge connector by ID. | `knowledgeSource:delete` |
| `assign_knowledge_connector_to_knowledge_base` | Assign a knowledge connector to a knowledge base. | `knowledgeSource:update` |
| `unassign_knowledge_connector_from_knowledge_base` | Remove a knowledge connector from a knowledge base. | `knowledgeSource:update` |
| `assign_knowledge_base_to_agent` | Assign a knowledge base to an agent. | `knowledgeSource:update` |
| `unassign_knowledge_base_from_agent` | Remove a knowledge base from an agent. | `knowledgeSource:update` |
| `assign_knowledge_connector_to_agent` | Directly assign a knowledge connector to an agent (bypassing knowledge base). | `knowledgeSource:update` |
| `unassign_knowledge_connector_from_agent` | Remove a directly-assigned knowledge connector from an agent. | `knowledgeSource:update` |

#### query_knowledge_sources

Required RBAC permission: `knowledgeSource:query`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | `string` | Yes | The user's original query, passed verbatim without rephrasing or expansion. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `results` | `any[]` | Yes | Retrieved knowledge results. |
| `totalChunks` | `number` | Yes | The number of result chunks returned. |

#### create_knowledge_base

Required RBAC permission: `knowledgeSource:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Name of the knowledge base. |
| `description` | `string \| null` | No | Description of the knowledge base. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeBase` | `object` | Yes | The requested knowledge base. |
| `knowledgeBase.id` | `string` | Yes | The knowledge base ID. |
| `knowledgeBase.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeBase.name` | `string` | Yes | The knowledge base name. |
| `knowledgeBase.description` | `string \| null` | Yes | The knowledge base description, if any. |
| `knowledgeBase.status` | `string` | Yes | The knowledge base status. |

#### get_knowledge_bases

Required RBAC permission: `knowledgeSource:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeBases` | `object[]` | Yes | Knowledge bases in the organization. |
| `knowledgeBases[].id` | `string` | Yes | The knowledge base ID. |
| `knowledgeBases[].organizationId` | `string` | Yes | The organization ID. |
| `knowledgeBases[].name` | `string` | Yes | The knowledge base name. |
| `knowledgeBases[].description` | `string \| null` | Yes | The knowledge base description, if any. |
| `knowledgeBases[].status` | `string` | Yes | The knowledge base status. |

#### get_knowledge_base

Required RBAC permission: `knowledgeSource:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge base ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeBase` | `object` | Yes | The requested knowledge base. |
| `knowledgeBase.id` | `string` | Yes | The knowledge base ID. |
| `knowledgeBase.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeBase.name` | `string` | Yes | The knowledge base name. |
| `knowledgeBase.description` | `string \| null` | Yes | The knowledge base description, if any. |
| `knowledgeBase.status` | `string` | Yes | The knowledge base status. |

#### update_knowledge_base

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge base ID. |
| `name` | `string` | No | New knowledge base name. |
| `description` | `string \| null` | No | New knowledge base description. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeBase` | `object` | Yes | The requested knowledge base. |
| `knowledgeBase.id` | `string` | Yes | The knowledge base ID. |
| `knowledgeBase.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeBase.name` | `string` | Yes | The knowledge base name. |
| `knowledgeBase.description` | `string \| null` | Yes | The knowledge base description, if any. |
| `knowledgeBase.status` | `string` | Yes | The knowledge base status. |

#### delete_knowledge_base

Required RBAC permission: `knowledgeSource:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge base ID. |


#### create_knowledge_connector

Required RBAC permission: `knowledgeSource:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | Name of the knowledge connector. |
| `connector_type` | `string` | Yes | Type of the knowledge connector (for example jira, confluence, or google_drive). |
| `config` | `object` | Yes | Provider-specific configuration object. |
| `description` | `string \| null` | No | Description of the knowledge connector. |
| `visibility` | `"org-wide" \| "team-scoped"` | No | Visibility for the knowledge connector. |
| `team_ids` | `string[]` | No | Team IDs allowed to access a team-scoped connector. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeConnector` | `object` | Yes | The requested knowledge connector. |
| `knowledgeConnector.id` | `string` | Yes | The knowledge connector ID. |
| `knowledgeConnector.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeConnector.knowledgeBaseId` | `string \| null` | No |  |
| `knowledgeConnector.name` | `string` | Yes | The connector name. |
| `knowledgeConnector.connectorType` | `string` | Yes | The connector type. |
| `knowledgeConnector.description` | `string \| null` | Yes | The connector description, if any. |
| `knowledgeConnector.enabled` | `boolean` | No |  |
| `knowledgeConnector.config` | `any` | Yes | The provider-specific connector configuration. |

#### get_knowledge_connectors

Required RBAC permission: `knowledgeSource:read`

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeConnectors` | `object[]` | Yes | Knowledge connectors in the organization. |
| `knowledgeConnectors[].id` | `string` | Yes | The knowledge connector ID. |
| `knowledgeConnectors[].organizationId` | `string` | Yes | The organization ID. |
| `knowledgeConnectors[].knowledgeBaseId` | `string \| null` | No |  |
| `knowledgeConnectors[].name` | `string` | Yes | The connector name. |
| `knowledgeConnectors[].connectorType` | `string` | Yes | The connector type. |
| `knowledgeConnectors[].description` | `string \| null` | Yes | The connector description, if any. |
| `knowledgeConnectors[].enabled` | `boolean` | No |  |
| `knowledgeConnectors[].config` | `any` | Yes | The provider-specific connector configuration. |

#### get_knowledge_connector

Required RBAC permission: `knowledgeSource:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge connector ID. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeConnector` | `object` | Yes | The requested knowledge connector. |
| `knowledgeConnector.id` | `string` | Yes | The knowledge connector ID. |
| `knowledgeConnector.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeConnector.knowledgeBaseId` | `string \| null` | No |  |
| `knowledgeConnector.name` | `string` | Yes | The connector name. |
| `knowledgeConnector.connectorType` | `string` | Yes | The connector type. |
| `knowledgeConnector.description` | `string \| null` | Yes | The connector description, if any. |
| `knowledgeConnector.enabled` | `boolean` | No |  |
| `knowledgeConnector.config` | `any` | Yes | The provider-specific connector configuration. |

#### update_knowledge_connector

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge connector ID. |
| `name` | `string` | No | New connector name. |
| `description` | `string \| null` | No | New connector description. |
| `enabled` | `boolean` | No | Whether the connector is enabled. |
| `visibility` | `"org-wide" \| "team-scoped"` | No | Updated visibility for the connector. |
| `team_ids` | `string[]` | No | Updated team IDs for a team-scoped connector. |
| `config` | `object` | No | Updated connector configuration (provider-specific settings). |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `knowledgeConnector` | `object` | Yes | The requested knowledge connector. |
| `knowledgeConnector.id` | `string` | Yes | The knowledge connector ID. |
| `knowledgeConnector.organizationId` | `string` | Yes | The organization ID. |
| `knowledgeConnector.knowledgeBaseId` | `string \| null` | No |  |
| `knowledgeConnector.name` | `string` | Yes | The connector name. |
| `knowledgeConnector.connectorType` | `string` | Yes | The connector type. |
| `knowledgeConnector.description` | `string \| null` | Yes | The connector description, if any. |
| `knowledgeConnector.enabled` | `boolean` | No |  |
| `knowledgeConnector.config` | `any` | Yes | The provider-specific connector configuration. |

#### delete_knowledge_connector

Required RBAC permission: `knowledgeSource:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | Yes | Knowledge connector ID. |


#### assign_knowledge_connector_to_knowledge_base

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | `string` | Yes | Knowledge connector ID. |
| `knowledge_base_id` | `string` | Yes | Knowledge base ID. |


#### unassign_knowledge_connector_from_knowledge_base

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | `string` | Yes | Knowledge connector ID. |
| `knowledge_base_id` | `string` | Yes | Knowledge base ID. |


#### assign_knowledge_base_to_agent

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | `string` | Yes | Knowledge base ID. |
| `agent_id` | `string` | Yes | Agent ID. |


#### unassign_knowledge_base_from_agent

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | `string` | Yes | Knowledge base ID. |
| `agent_id` | `string` | Yes | Agent ID. |


#### assign_knowledge_connector_to_agent

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | `string` | Yes | Knowledge connector ID. |
| `agent_id` | `string` | Yes | Agent ID. |


#### unassign_knowledge_connector_from_agent

Required RBAC permission: `knowledgeSource:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | `string` | Yes | Knowledge connector ID. |
| `agent_id` | `string` | Yes | Agent ID. |


### Chat

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `todo_write` | Write todos to the current conversation. | None (no additional RBAC permission required) |
| `swap_agent` | Switch the current conversation to a different agent. | `agent:read` |
| `swap_to_default_agent` | Return to the default agent. | None (no additional RBAC permission required) |
| `create_project_from_conversation` | Turn the current chat into a project. | `project:create` |

#### todo_write

Required RBAC permission: None (no additional RBAC permission required)

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `todos` | `object[]` | Yes | Array of todo items to write to the conversation. |
| `todos[].id` | `integer` | Yes | Unique identifier for the todo item. |
| `todos[].content` | `string` | Yes | The content or description of the todo item. |
| `todos[].status` | `"pending" \| "in_progress" \| "completed"` | Yes | The current status of the todo item. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the write succeeded. |
| `todoCount` | `integer` | Yes | How many todo items were written. |

#### swap_agent

Required RBAC permission: `agent:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_name` | `string` | Yes | The name of the agent to switch to. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the swap succeeded. |
| `agent_id` | `string` | Yes | The agent ID the conversation now uses. |
| `agent_name` | `string` | Yes | The agent name the conversation now uses. |

#### swap_to_default_agent

Required RBAC permission: None (no additional RBAC permission required)

This tool takes no arguments.

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the swap succeeded. |
| `agent_id` | `string` | Yes | The agent ID the conversation now uses. |
| `agent_name` | `string` | Yes | The agent name the conversation now uses. |

#### create_project_from_conversation

Required RBAC permission: `project:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | No | Project name. Defaults to the chat's title when omitted. |
| `description` | `string` | No | Optional project description. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | `boolean` | Yes | Whether the project was created. |
| `project_id` | `string` | Yes | The new project's id. |
| `project_name` | `string` | Yes | The new project's name. |
| `project_slug` | `string` | Yes | The new project's slug. |
| `files_transferred` | `integer` | Yes | How many of the chat's files were moved into the project. |

### Meta

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `search_tools` | Search the tools available to this agent and to you on demand. | None (no additional RBAC permission required) |
| `run_tool` | Dispatch to any tool available to this agent, including built-in platform tools, agent delegation tools ('agent-<id>'), or third-party MCP tools exposed through the MCP Gateway (e.g. | None (no additional RBAC permission required) |

#### search_tools

Required RBAC permission: None (no additional RBAC permission required)

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | `string` | Yes | Keywords for the capability you need — combine the action (verb + object) with the server/product name when you know it, e.g. 'github search repositories' or 'slack send message'. Avoid querying with a bare product/server name on its own. Results are keyword-ranked across tool names, descriptions, and argument names/descriptions. If nothing fits, reformulate with different keywords and search again rather than settling for a poor match. |
| `limit` | `integer` | No | Maximum number of matching tools to return. |
| `mode` | `"keyword" \| "regex"` | No | Search mode. 'keyword' (default) keyword-ranks the query across tool fields. 'regex' treats query as a case-insensitive regular expression matched against tool names, titles, and descriptions — use it when you know a naming pattern, e.g. '^github__' or 'search\|find'. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `total` | `integer` | Yes | Number of returned tools. |
| `matchCount` | `integer` | Yes | Total tools matching the query before the limit was applied (>= total). |
| `truncated` | `boolean` | Yes | True when matchCount exceeds the returned tools (results cut by limit). |
| `hint` | `string \| null` | Yes | Actionable guidance when results were truncated or empty (an empty result also names which query terms matched no tool text). |
| `tools` | `object[]` | Yes |  |
| `tools[].toolName` | `string` | Yes | Exact tool name to pass to run_tool. |
| `tools[].description` | `string \| null` | Yes | Short tool description, if available. |
| `tools[].source` | `"archestra" \| "mcp" \| "agent_delegation"` | Yes | Where the tool comes from. |
| `tools[].server` | `string \| null` | Yes | MCP server prefix for third-party MCP tools when available. |
| `tools[].available` | `boolean` | Yes | False when the tool's MCP connection is not installed; it stays discoverable but cannot run until reconnected. |
| `tools[].unavailableReason` | `string \| null` | Yes | Compact reason and recovery action when available is false; null otherwise. |
| `tools[].params` | `string` | Yes | Compact one-line input signature — a summary, not the full schema. Parameters are joined by '; ', each rendered as `name<!\|?>:<type>` where `!` marks required and `?` optional. Object parameters are expanded up to two levels as `{child<!\|?>:type{grandchild<!\|?>:type}, …}`, enums as `enum(<json-values>)`, and a trailing ` — description` is added when available. A trailing `…` on a type marks an object whose content is not fully shown (freeform or more deeply nested) — consult the task instructions or the full schema for its shape. Empty string when the tool takes no input. Pass matching values inside tool_args when calling run_tool; if a call is rejected as invalid, the error describes the expected input (for third-party tools, the full input schema). |

#### run_tool

Required RBAC permission: None (no additional RBAC permission required)

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tool_name` | `string` | Yes | Name of the tool to invoke. Use the exact name as it appears in the tools list, e.g. 'archestra__whoami', 'context7__resolve-library-id', or an agent delegation name 'agent-<id>'. |
| `tool_args` | `object` | No | Arguments object for the target tool; must match its input schema. |


### Skills

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `list_skills` | List the Agent Skills available in this organization — one line per skill (name and description). | `skill:read` |
| `load_skill` | Load a specialized Agent Skill — a reusable SKILL.md instruction set. | `skill:read` |
| `create_skill` | Create a new Agent Skill from a SKILL.md manifest. | `skill:create` |
| `update_skill` | Update an existing Agent Skill from a SKILL.md manifest. | `skill:update` |

#### list_skills

Required RBAC permission: `skill:read`

This tool takes no arguments.


#### load_skill

Required RBAC permission: `skill:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | The skill to load, as named by list_skills. |
| `path` | `string` | No | Optional. Omit (or pass an empty string) to load the skill's instructions and bundled-file list. Pass a resource path from that list (e.g. references/REFERENCE.md) to read one bundled file instead. |


#### create_skill

Required RBAC permission: `skill:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | `string` | Yes | A complete SKILL.md manifest: a YAML frontmatter block with `name` and `description` (and optional `license`, `compatibility`, `allowed-tools`, `templated`, `metadata`), followed by the Markdown instruction body. Set `templated: true` to render the body through Handlebars (e.g. `{{user.name}}`) at activation. `allowed-tools` is a space-separated list of tools the skill is pre-approved to use. |
| `files` | `object[]` | No | Optional bundled resource files. Each is `{ path, content }` with text content; the path prefix classifies the file — `references/` for docs, `scripts/` for code, `assets/` for other files. |
| `files[].path` | `string` | Yes | Resource path, e.g. references/API.md or scripts/run.py |
| `files[].content` | `string` | Yes | Text content of the file |
| `files[].encoding` | `"utf8" \| "base64"` | No |  |


#### update_skill

Required RBAC permission: `skill:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | The current name of the skill to update, as named by list_skills. |
| `content` | `string` | Yes | A complete SKILL.md manifest: a YAML frontmatter block with `name` and `description` (and optional `license`, `compatibility`, `allowed-tools`, `templated`, `metadata`), followed by the Markdown instruction body. Set `templated: true` to render the body through Handlebars (e.g. `{{user.name}}`) at activation. `allowed-tools` is a space-separated list of tools the skill is pre-approved to use. |
| `files` | `object[]` | No | Optional. WHEN PROVIDED, REPLACES THE SKILL'S ENTIRE bundled file set. Omit it to leave the existing resource files untouched. There is no per-file patch: to change one file you must resend all of them — read the current files back first with load_skill (with and without a path). |
| `files[].path` | `string` | Yes | Resource path, e.g. references/API.md or scripts/run.py |
| `files[].content` | `string` | Yes | Text content of the file |
| `files[].encoding` | `"utf8" \| "base64"` | No |  |


### Apps

| Tool | Description | Required RBAC Permission |
|------|-------------|--------------------------|
| `scaffold_app` | Create a new interactive app (dashboard, form, tracker, game, or any custom UI) seeded from the default starter template. | `app:create` |
| `refine_app` | Clarify what an existing app should be and record it as a persisted product spec, between scaffold_app and edit_app. | `app:update` |
| `list_apps` | List apps visible to the caller, optionally filtered by name — use it to find an app's id. | `app:read` |
| `render_app` | Render an existing app by id, if the caller may view it. | `app:read` |
| `read_app` | Return an app's stored HTML (pre-injection — exactly what was saved, without the platform SDK or base stylesheet) plus its version, byte size, name, and scope. | `app:read` |
| `edit_app` | The single path for any change to an app's HTML: pass edits for targeted str_replace changes, or replacementHtml to swap in a complete new document (no old_str matching) — one or the other, never b... | `app:update` |
| `set_app_tools` | Replace an existing app's assigned upstream tools with exactly the set you pass (the full desired list; [] clears all). | `app:update` |
| `validate_app` | The pre-publish gate for an app's head version: static structural checks (`findings`, each carrying its own specific message) plus the most recent live-render diagnostics (`live`), with `ok` true w... | `app:read` |
| `publish_app` | Share an app with others: promote it out of personal scope so others can run it — this is how you distribute or make an app available to a team or the whole org — to specific teams (scope: team, wi... | `app:update` |
| `preview_app_tool` | Run one of an app's assigned MCP tools server-side, exactly as the rendered app would (as you, the viewing user, with your MCP credentials), and return its real output. | `app:update` |
| `get_app_diagnostics` | Check how the app's current version rendered for you. | `app:read` |
| `delete_app` | Soft-delete an app the caller owns or administers, and remove its MCP backing so it is no longer served. | `app:delete` |
| `app_data_get` | Read a value from the calling app's data store (per-user or shared partition). | `app:read` |
| `app_data_set` | Write a value to the calling app's data store (per-user or shared partition). | `app:update` |
| `app_data_list` | List all entries in one partition of the calling app's data store. | `app:read` |
| `app_data_delete` | Delete a key from the calling app's data store (per-user or shared partition). | `app:update` |
| `llm_complete` | Run a single LLM completion for the calling app (backs archestra.llm.complete). | `app:read` |

#### scaffold_app

Required RBAC permission: `app:create`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | Yes | App name. |
| `description` | `string` | No | Optional description. |
| `scope` | `"personal" \| "team" \| "org"` | No | Visibility scope, personal (default, owned by the calling user) or org. Team scope is not available here — team-scoped apps must be created in the Apps UI so teams can be assigned. |
| `uiPermissions` | `object` | No | Optional iframe permissions (camera/microphone/geolocation/clipboardWrite). |
| `uiPermissions.camera` | `object` | No |  |
| `uiPermissions.microphone` | `object` | No |  |
| `uiPermissions.geolocation` | `object` | No |  |
| `uiPermissions.clipboardWrite` | `object` | No |  |
| `tools` | `string[]` | No | Upstream MCP tool names to assign to the new app (e.g. from search_tools), callable from its HTML via archestra.tools.call with the viewing user's credentials. Omitted leaves the app with no assigned tools. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `name` | `string` | Yes |  |
| `description` | `string \| null` | Yes |  |
| `scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `latestVersion` | `number` | Yes |  |
| `warnings` | `string[]` | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. |
| `tools` | `string[]` | No | The app's assigned tool names after this call (present when the tools param was given). |
| `status` | `"ok" \| "partial"` | No | Absent or "ok" on full success. "partial" means the app was created (see id) but assigning its tools failed — the app exists; assign them with set_app_tools rather than re-scaffolding. |

#### refine_app

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id to refine. |
| `questions` | `object[]` | No | Up to 3 clarifying questions to ask the user before consolidating the spec. |
| `questions[].id` | `string` | Yes | Stable key the answer is returned under. |
| `questions[].prompt` | `string` | Yes | The question shown to the user. |
| `questions[].options` | `string[]` | No | When present, the question is single-select over these plain-string option labels, e.g. ["Light", "Dark"] — never {label, value} objects; otherwise it is free-text. |
| `spec` | `object` | No | The consolidated product requirements to persist on the app (features/data/ui/tools — no implementation stack). |
| `spec.summary` | `string` | Yes |  |
| `spec.features` | `string[]` | Yes |  |
| `spec.data` | `string \| null` | No |  |
| `spec.ui` | `string \| null` | No |  |
| `spec.tools` | `string[]` | Yes |  |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `spec` | `object` | Yes | The persisted spec when one was given, else the base spec seeded for the model. |
| `spec.summary` | `string` | Yes |  |
| `spec.features` | `string[]` | Yes |  |
| `spec.data` | `string \| null` | No |  |
| `spec.ui` | `string \| null` | No |  |
| `spec.tools` | `string[]` | Yes |  |
| `capability` | `object` | Yes |  |
| `capability.tools` | `object[]` | Yes |  |
| `capability.tools[].name` | `string` | Yes |  |
| `capability.tools[].description` | `string` | Yes |  |
| `capability.sdkSummary` | `string` | Yes |  |
| `answers` | `object` | No | The user's answers to the clarifying questions, if any. |
| `persisted` | `boolean` | Yes | Whether a spec was persisted on the app head by this call. |

#### list_apps

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `string` | No | Filter by name (substring match). |
| `limit` | `integer` | No |  |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `apps` | `object[]` | Yes |  |
| `apps[].id` | `string` | Yes |  |
| `apps[].name` | `string` | Yes |  |
| `apps[].description` | `string \| null` | Yes |  |
| `apps[].scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `apps[].latestVersion` | `number` | Yes |  |
| `apps[].warnings` | `string[]` | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. |

#### render_app

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `name` | `string` | Yes |  |
| `description` | `string \| null` | Yes |  |
| `scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `latestVersion` | `number` | Yes |  |
| `warnings` | `string[]` | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. |

#### read_app

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id. |
| `version` | `integer` | No | Specific version to read; defaults to the current head. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `name` | `string` | Yes |  |
| `scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `version` | `number` | Yes |  |
| `byteSize` | `number` | Yes |  |
| `html` | `string` | Yes | The stored HTML, pre-injection (no SDK/base CSS). |

#### edit_app

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id. |
| `baseVersion` | `integer` | Yes | The version the edits are based on (from read_app). The edit is rejected if the app's head has moved past it. |
| `edits` | `object[]` | No | str_replace edits applied in order to the current HTML; the whole edit is atomic (any failure leaves the app unchanged). Pass either edits or replacementHtml, never both. |
| `edits[].old_str` | `string` | Yes | Exact text to replace; must occur exactly once in the current HTML (add surrounding context to disambiguate). |
| `edits[].new_str` | `string` | Yes | Replacement text (may be empty to delete). |
| `replacementHtml` | `string` | No | The complete new document, replacing the current HTML outright with no old_str matching — use this for a full rewrite instead of reproducing the whole document as an edit. Pass either edits or replacementHtml, never both. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `name` | `string` | Yes |  |
| `description` | `string \| null` | Yes |  |
| `scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `latestVersion` | `number` | Yes |  |
| `warnings` | `string[]` | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. |

#### set_app_tools

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id whose tools to set. |
| `tools` | `string[]` | Yes | Upstream MCP tool names (e.g. from search_tools) to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `tools` | `string[]` | Yes | The app's assigned tool names after this call. |

#### validate_app

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id to validate. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `version` | `number` | Yes | The head version that was validated. |
| `ok` | `boolean` | Yes | True when there are no error-severity findings. |
| `findings` | `object[]` | Yes |  |
| `findings[].severity` | `"error" \| "warning"` | Yes |  |
| `findings[].message` | `string` | Yes |  |
| `live` | `object` | Yes | Diagnostics from the most recent live render of the head version (untrusted iframe output). status no_render_observed means no render of this version has happened yet — live diagnostics are captured only when the app renders for a viewer, so this is the normal state right after authoring and a clean static pass (ok: true) is enough to proceed. |
| `live.status` | `"no_render_observed" \| "clean" \| "errors"` | Yes |  |
| `live.version` | `number` | Yes |  |
| `live.entries` | `object[]` | Yes |  |
| `live.entries[].type` | `string` | Yes |  |
| `live.entries[].message` | `string` | Yes |  |
| `live.renderedAt` | `string \| null` | Yes |  |

#### publish_app

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id to publish. |
| `scope` | `"team" \| "org"` | Yes | Publish to specific teams or to the whole organization. Promotes the app out of personal scope. |
| `teams` | `string[]` | No | Target teams, each a team name or team id — required when scope is team. Pass the team name the user gave (e.g. ["Platform"]); no need to look up ids first. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `scope` | `"personal" \| "team" \| "org"` | Yes |  |
| `runUrl` | `string` | Yes | Standalone page for the published app. |

#### preview_app_tool

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id whose assigned tool to run. |
| `toolName` | `string` | Yes | Name of an MCP tool assigned to the app (exactly as archestra.tools.call would receive it). |
| `args` | `object` | No | Arguments to pass to the tool (defaults to {}). |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `toolName` | `string` | Yes |  |
| `isError` | `boolean` | Yes |  |
| `truncated` | `boolean` | Yes |  |
| `output` | `string` | Yes | The JSON-serialized value archestra.tools.call resolves with for this result, framed as untrusted data (media dataUrls are elided). |

#### get_app_diagnostics

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | `"no_render_observed" \| "clean" \| "errors"` | Yes |  |
| `version` | `number \| null` | Yes | The rendered version, or the current head when none observed. |
| `entries` | `object[]` | Yes |  |
| `entries[].type` | `string` | Yes |  |
| `entries[].message` | `string` | Yes |  |
| `renderedAt` | `string \| null` | Yes |  |
| `screenshot` | `boolean` | Yes | Whether a screenshot of the render is attached as an image to this result. |

#### delete_app

Required RBAC permission: `app:delete`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | `string` | Yes | The app id. |


#### app_data_get

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | `string` | Yes | The data store key. |
| `scope` | `"user" \| "app"` | No | Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | `any` | Yes |  |
| `revision` | `integer \| null` | Yes |  |
| `owner` | `string \| null` | Yes | User id owning a shared key, or null if collaborative. |

#### app_data_set

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | `string` | Yes | The data store key. |
| `value` | `any` | Yes | Any JSON-serializable value except null (use app_data_delete to clear a key). Pass objects/arrays directly — get returns exactly what was stored, no JSON.stringify needed. |
| `scope` | `"user" \| "app"` | No | Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app. |
| `expectedRevision` | `integer` | No | Optimistic concurrency guard. Omit for last-writer-wins. 0 = create only if the key is absent. A positive value = overwrite only if the key is still at that revision (from a prior get/set); otherwise the write is rejected as a conflict. |
| `claimOwner` | `boolean` | No | Shared-scope only: when creating a NEW key, claim it so only you (or an app admin/author) may later overwrite or delete it. Has no effect on the "user" scope or on an existing key. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | `string` | Yes |  |
| `revision` | `integer` | Yes |  |
| `owner` | `string \| null` | Yes | User id owning a shared key, or null if collaborative. |

#### app_data_list

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | `"user" \| "app"` | No | Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app. |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `entries` | `object[]` | Yes |  |
| `entries[].key` | `string` | Yes |  |
| `entries[].value` | `any` | Yes |  |
| `entries[].revision` | `integer` | Yes |  |
| `entries[].owner` | `string \| null` | Yes | User id owning a shared key, or null if collaborative. |

#### app_data_delete

Required RBAC permission: `app:update`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | `string` | Yes | The data store key. |
| `scope` | `"user" \| "app"` | No | Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app. |


#### llm_complete

Required RBAC permission: `app:read`

##### Input

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `string` | Yes | The prompt to complete. |
| `system` | `string` | No | Optional system instruction that frames the completion. |
| `jsonMode` | `boolean` | No | When true, steer the model to return a single valid JSON value (the caller still parses the returned string). |

##### Output

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | `string` | Yes |  |
