Built-in MCP server providing tools for managing Archestra platform resources
140 min read
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, query_knowledge_sources.
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 is an exception: its output is treated as sensitive by default and is evaluated by trusted data policies. See AI Tool Guardrails for more details.
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 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
list_hooks
List an agent's lifecycle hooks.
agent:read
create_hook
Create a lifecycle hook on an agent.
agent:update
update_hook
Update an existing lifecycle hook: its event, file name, script content, Python requirements, or enabled state.
agent:update
delete_hook
Delete a lifecycle hook by ID.
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 — and persistent-files tools (search_files, read_file, save_file, edit_file, delete_file) — when the Projects feature is enabled and assigned — stay directly available in both modes. App tools (scaffold_app, edit_app, read_app, render_app, list_apps, and the rest of the app surface) are reached through search_tools/run_tool in 'search_and_run_only' mode.
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.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
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.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent 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'.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions).
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.
list_hooks
Required RBAC permission: agent:read
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hooks[].content
string
Yes
The script content.
hooks[].requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hooks[].enabled
boolean
Yes
Whether the hook currently fires.
hooks[].createdAt
string
Yes
ISO timestamp when the hook was created.
hooks[].updatedAt
string
Yes
ISO timestamp when the hook was last updated.
create_hook
Required RBAC permission: agent:update
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
update_hook
Required RBAC permission: agent:update
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
delete_hook
Required RBAC permission: agent:update
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the hook to delete.
Output
Field
Type
Required
Description
success
boolean
Yes
id
string
Yes
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.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
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.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent 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
reload_mcp_server_tools
Re-discover a deployed MCP server's tools from the live server and refresh Archestra's tool catalog for it — picks up added, removed, and changed tools (names, descriptions, and input schemas) with...
mcpRegistry:update
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.
[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. Pass null for the default environment. Omit it to use your own environment, or the organization's landing environment for new MCP servers when you have none.
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.
[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.
reload_mcp_server_tools
Required RBAC permission: mcpRegistry:update
Input
Parameter
Type
Required
Description
serverId
string
Yes
The deployment ID of the MCP server whose tools should be refreshed. Use list_mcp_server_deployments to find it.
Teams
Tool
Description
Required RBAC Permission
create_team
Create a new team in the organization, optionally nested under a parent team and with key-value labels.
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, description, parent, and/or labels.
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 †
list_team_external_groups
List the external identity provider groups mapped to a team for SSO team sync.
team:read
add_team_external_group
Map an external identity provider group to a team for SSO team sync: users whose SSO group memberships match are automatically added to or removed from the team on login.
team:read
remove_team_external_group
Remove an external group mapping from a team's SSO team sync, by mapping ID or by group identifier.
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.
roles
string[]
No
Organization role identifiers to assign to the team. Members of this team and its descendants inherit their permissions.
parent_id
string | null
No
Optional parent team ID. Omit or pass null for a root team.
labels
object[]
No
Optional key-value labels to assign to the team for organization and categorization (e.g. cost-center, environment).
labels[].key
string
Yes
labels[].value
string
Yes
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.roles
string[]
Yes
Organization role identifiers assigned to the team and inherited by members of this team and its descendants.
team.parentId
string | null
Yes
The parent team ID, or null when this is a root team.
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.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
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.roles
string[]
Yes
Organization role identifiers assigned to the team and inherited by members of this team and its descendants.
team.parentId
string | null
Yes
The parent team ID, or null when this is a root team.
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.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
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[].roles
string[]
Yes
Organization role identifiers assigned to the team and inherited by members of this team and its descendants.
teams[].parentId
string | null
Yes
The parent team ID, or null when this is a root team.
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[].labels
object[]
Yes
Key-value labels assigned to the team.
teams[].labels[].key
string
Yes
The label key.
teams[].labels[].value
string
Yes
The label value.
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.
roles
string[]
No
Replace the team’s organization role identifiers. Members of this team and its descendants inherit their permissions. Pass [] to clear; omit to leave unchanged.
parent_id
string | null
No
Move the team under this parent. Pass null to move it to the root; omit to leave the hierarchy unchanged.
labels
object[]
No
Replace the team's labels with this set. Pass an empty array to remove all labels. Omit to leave labels unchanged.
labels[].key
string
Yes
labels[].value
string
Yes
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.roles
string[]
Yes
Organization role identifiers assigned to the team and inherited by members of this team and its descendants.
team.parentId
string | null
Yes
The parent team ID, or null when this is a root team.
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.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
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
list_team_external_groups
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team whose external group mappings to list.
Output
Field
Type
Required
Description
externalGroups
object[]
Yes
externalGroups[].id
string
Yes
The external group mapping ID.
externalGroups[].teamId
string
Yes
The team the mapping belongs to.
externalGroups[].groupIdentifier
string
Yes
The external identity provider group identifier.
externalGroups[].createdAt
string
Yes
ISO timestamp when the mapping was created.
add_team_external_group
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team to map the external group to.
group_identifier
string
Yes
The external identity provider group identifier. Format varies by provider: LDAP Distinguished Name (e.g. cn=admins,ou=groups,dc=example,dc=com), OAuth/OIDC group name from the groups claim, SAML group attribute value, or Azure AD group object ID (GUID). Matched case-insensitively.
Output
Field
Type
Required
Description
externalGroup
object
Yes
externalGroup.id
string
Yes
The external group mapping ID.
externalGroup.teamId
string
Yes
The team the mapping belongs to.
externalGroup.groupIdentifier
string
Yes
The external identity provider group identifier.
externalGroup.createdAt
string
Yes
ISO timestamp when the mapping was created.
remove_team_external_group
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
group_id
string
No
The ID of the external group mapping to remove.
group_identifier
string
No
The external group identifier to remove, as an alternative to group_id. Matched case-insensitively.
Output
Field
Type
Required
Description
success
boolean
Yes
teamId
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 the LLM Proxy.
Assign multiple tools to multiple agents in bulk with validation and error handling
agent:update
bulk_remove_tools_from_agents
Remove multiple tools from multiple agents in bulk.
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" | "forbidden"
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" | "forbidden"
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" | "forbidden"
No
Structured assignment error code.
duplicates[].errorType
string
No
Structured assignment error type.
bulk_remove_tools_from_agents
Required RBAC permission: agent:update
Input
Parameter
Type
Required
Description
removals
object[]
Yes
Tool removals to apply to agents.
removals[].agentId
string
Yes
The agent ID to remove the tool from.
removals[].toolId
string
Yes
The ID of the tool to remove.
Output
Field
Type
Required
Description
succeeded
object[]
Yes
Removals that took effect.
succeeded[].agentId
string
Yes
The target agent ID.
succeeded[].toolId
string
Yes
The tool ID.
succeeded[].error
string
No
Permission or removal error.
notAssigned
object[]
Yes
Removals skipped because the tool was not assigned to the agent (Custom mode).
notAssigned[].agentId
string
Yes
The target agent ID.
notAssigned[].toolId
string
Yes
The tool ID.
notAssigned[].error
string
No
Permission or removal error.
failed
object[]
Yes
Removals that failed (e.g. no permission, agent not found, or a tool that cannot be excluded).
failed[].agentId
string
Yes
The target agent ID.
failed[].toolId
string
Yes
The tool ID.
failed[].error
string
No
Permission or removal error.
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" | "forbidden"
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" | "forbidden"
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" | "forbidden"
No
Structured assignment error code.
duplicates[].errorType
string
No
Structured assignment error type.
Knowledge Management
Tool
Description
Required RBAC Permission
query_knowledge_sources
Search the organization's indexed knowledge — documents, files, images, photos, and records synced from its connected sources.
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.
documentFilter
object
No
Optional. Narrows the search to a subset of the indexed documents by their source metadata — for example {"spaceKey": "DEV"} or {"labels": ["release-2.0"]}. Keys are ANDed; a list of values for one key is ORed. Matches both single values and list-valued metadata. Only use this when the user's request explicitly names a subset to search; do NOT infer one from the topic of the question, and do NOT guess key or value names. If a filter matches nothing, the response lists the values that actually exist so the call can be retried with a real one.
Output
Field
Type
Required
Description
results
any[]
Yes
Retrieved knowledge results.
totalChunks
number
Yes
The number of result chunks returned.
citationInstruction
string
No
How to cite these results: back each claim with a verbatim quote tagged with the source chunk's ref.
filterDiagnostic
string
No
Present only when documentFilter matched no documents. Names the values that do exist for the keys that were filtered on, so the search can be retried.
create_knowledge_base
Required RBAC permission: knowledgeSource:create
Input
Parameter
Type
Required
Description
visibility
"private" | "org-wide" | "team-scoped"
No
teamIds
string[]
No
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
visibility
"private" | "org-wide" | "team-scoped"
No
teamIds
string[]
No
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).
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.
Projects
Tool
Description
Required RBAC Permission
create_project_from_conversation
Turn the current chat into a project.
project:create
set_project_share
Change who can see a project: the whole organization ("organization"), specific teams ("team"), or only the owner ("none").
project:update †
list_projects
List the projects the caller can reach — the ones they own plus those shared with them.
project:read †
get_project
Read one project's context in a single call: its metadata, its instructions (the instructions.md that steers every chat in the project), and the list of files it owns.
project:read †
† This tool enforces an additional access requirement beyond its RBAC permission — see its details below.
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.
labels
object[]
No
Optional key/value labels for the project.
labels[].key
string
Yes
labels[].value
string
Yes
labels[].keyId
string
No
labels[].valueId
string
No
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.
set_project_share
Required RBAC permission: project:update
Additional access requirement: Beyond project:update, the caller must own the project (or hold project:admin), and moving a project into or out of organization-wide visibility additionally requires project:share-org.
Input
Parameter
Type
Required
Description
visibility
"organization" | "team" | "none"
Yes
Who can see the project: "organization" for everyone in the organization, "team" for the given teams, "none" to make it owner-only.
team_ids
string[]
No
Ids of the teams to share with. Required when visibility is "team"; ignored otherwise.
project_id
string
No
Project to change. Defaults to the current chat's project.
Output
Field
Type
Required
Description
success
boolean
Yes
Whether the sharing was updated.
project_id
string
Yes
The affected project's id.
project_name
string
Yes
The affected project's name.
visibility
"organization" | "team" | "none"
Yes
The project's sharing after the update.
list_projects
Required RBAC permission: project:read
Additional access requirement: Returns only projects the caller owns or that are shared with them. project:admin oversight of other members' projects does not extend to this tool.
Input
Parameter
Type
Required
Description
query
string
No
Case-insensitive substring matched against the project name and description. Omit to list everything the caller can reach.
Output
Field
Type
Required
Description
projects
object[]
Yes
Projects the caller can reach.
projects[].id
string
Yes
The project's id — pass it to get_project.
projects[].name
string
Yes
The project's name.
projects[].description
string | null
Yes
The project's description.
projects[].visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
projects[].viewer_role
"owner" | "shared" | "admin"
Yes
The caller's relationship to the project.
projects[].owner_name
string | null
Yes
Display name of the owner.
projects[].labels
object[]
Yes
Key/value labels assigned to the project.
projects[].labels[].key
string
Yes
projects[].labels[].value
string
Yes
projects[].labels[].keyId
string
No
projects[].labels[].valueId
string
No
projects[].conversation_count
integer
Yes
How many chats live in the project.
projects[].created_at
string
Yes
ISO 8601 creation timestamp.
get_project
Required RBAC permission: project:read
Additional access requirement: Readable only for projects the caller owns or that are shared with them. project:admin oversight of other members' projects does not extend to this tool.
Input
Parameter
Type
Required
Description
project_id
string
Yes
Id of the project to read (from list_projects).
Output
Field
Type
Required
Description
id
string
Yes
The project's id — pass it to get_project.
name
string
Yes
The project's name.
description
string | null
Yes
The project's description.
visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
viewer_role
"owner" | "shared" | "admin"
Yes
The caller's relationship to the project.
owner_name
string | null
Yes
Display name of the owner.
labels
object[]
Yes
Key/value labels assigned to the project.
labels[].key
string
Yes
labels[].value
string
Yes
labels[].keyId
string
No
labels[].valueId
string
No
conversation_count
integer
Yes
How many chats live in the project.
created_at
string
Yes
ISO 8601 creation timestamp.
instructions
string
Yes
The project's instructions markdown; empty when never saved. Truncated when instructions_truncated is true.
instructions_truncated
boolean
Yes
Whether instructions was cut short at the inline limit.
files
object[]
Yes
Files the project owns. Read one with read_file, passing the same project_id and this ref.
files[].id
string
Yes
The file's id.
files[].ref
string
Yes
Stable reference to pass to read_file.
files[].filename
string
Yes
The file's name.
files[].mime_type
string
Yes
The file's MIME type.
files[].size_bytes
integer
Yes
Size in bytes.
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-'), 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-'.
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
edit_skill
Make a targeted edit to an existing Agent Skill without resending the whole SKILL.md.
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, agent, 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. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
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, agent, 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. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
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
edit_skill
Required RBAC permission: skill:update
Input
Parameter
Type
Required
Description
name
string
Yes
The current name of the skill to edit, as named by list_skills.
baseVersion
integer
Yes
The version the edit is based on — the version shown on the <skill_content>/<skill_file> frame you loaded with load_skill. The edit is rejected if the skill's head has moved past it.
path
string
No
Omit (or pass an empty string) to edit the SKILL.md body; pass a bundled file path (from the <skill_resources> list) to edit that file instead. Only text (utf8) files are editable — binary assets are not.
edits
object[]
No
str_replace edits applied in order to the target; the whole edit is atomic (any failure leaves the skill unchanged). This is the way to change a large SKILL.md without resending it all. Pass either edits or replacementContent, never both.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementContent
string
No
The complete new content of the target, replacing it outright with no old_str matching — use it for a small file or a full rewrite. Prefer edits for the SKILL.md body so you don't resend the whole thing. Pass either edits or replacementContent, never both.
Plugins
Tool
Description
Required RBAC Permission
list_plugins
List the plugins available to you in this organization — one line per plugin with its id, client, platforms, visibility, and file count.
plugin:read
get_plugin
Read one plugin, including every file's exact bytes and the plugin's current contentHash.
plugin:admin
create_plugin
Create a plugin from an explicit file set.
plugin:admin
update_plugin
Update a plugin's metadata, visibility, or entire file set.
plugin:admin
edit_plugin
Make a targeted edit to one file of a plugin without resending the whole file set.
The coding client the payload targets: claude-code, codex, copilot-cli, or cursor.
supportedPlatforms
string[]
No
Operating systems the payload supports.
scope
"personal" | "team" | "org"
No
Who can discover the plugin: personal (author plus named users), team, or org.
teamIds
string[]
No
Teams a team-scoped plugin is shared with.
userIds
string[]
No
Organization members a personal plugin is shared with.
files
object[]
Yes
The plugin's files as { path, content, encoding?, mode? }. Hook configuration bytes are stored verbatim — review them as code, they execute on developer machines.
files[].path
string
Yes
files[].content
string
Yes
files[].encoding
"utf8" | "base64"
No
files[].mode
"100644" | "100755"
No
update_plugin
Required RBAC permission: plugin:admin
Input
Parameter
Type
Required
Description
id
string
Yes
The plugin id, as listed by list_plugins.
displayName
string
No
Human-readable plugin name.
description
string
No
What the plugin does.
enabled
boolean
No
Disabled plugins are left out of future setup commands; already-installed copies are unaffected.
supportedPlatforms
string[]
No
Operating systems the payload supports.
scope
"personal" | "team" | "org"
No
Who can discover the plugin: personal (author plus named users), team, or org.
teamIds
string[]
No
Teams a team-scoped plugin is shared with.
userIds
string[]
No
Organization members a personal plugin is shared with.
baseContentHash
string
No
Required when files is provided. Use the current contentHash from get_plugin; the replacement is rejected if newer bytes landed first.
files
object[]
No
WHEN PROVIDED, REPLACES THE PLUGIN'S ENTIRE file set. Omit it to edit only metadata/visibility. Manual plugins only — GitHub-sourced files are read-only. For a small change to one file, prefer edit_plugin over resending every file.
files[].path
string
Yes
files[].content
string
Yes
files[].encoding
"utf8" | "base64"
No
files[].mode
"100644" | "100755"
No
edit_plugin
Required RBAC permission: plugin:admin
Input
Parameter
Type
Required
Description
id
string
Yes
The plugin id, as listed by list_plugins.
baseContentHash
string
Yes
The plugin's current contentHash, as returned by get_plugin. The edit is rejected when the plugin's bytes have moved past it.
path
string
Yes
The plugin file to edit, from the file list returned by get_plugin. Only text (utf8) files are editable — binary files are not.
edits
object[]
No
str_replace edits applied in order to the target file; the whole edit is atomic (any failure leaves the plugin unchanged). Pass either edits or replacementContent, never both.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementContent
string
No
The complete new content of the target file, replacing it outright with no old_str matching. Pass either edits or replacementContent, never both.
delete_plugin
Required RBAC permission: plugin:admin
Input
Parameter
Type
Required
Description
id
string
Yes
The plugin id, as listed by list_plugins.
Agent Runtime
Tool
Description
Required RBAC Permission
delete_workspace
Permanently delete a retained runtime workspace and all of its files.
agent:read
read_workspace_file
Read a file from your Agent Runtime's retained workspace using a run ID.
agent:read
write_workspace_file
Create a file in your Agent Runtime's retained workspace using a run ID.
agent:read
start_run
Start long-running work on an agent as a durable run and return immediately with its id.
agent:read
get_run
Read a run's state and the output it has produced so far.
agent:read
list_runs
List your runs on one agent, newest activity first.
agent:read
list_agent_runs
List recent runs across one or more accessible Agents for a read-only operations dashboard.
agent:read
steer_run
Interject one message into a live run's container session — a course correction without stopping the work.
agent:read
cancel_run
Stop an active run.
agent:read
post_run_file
Upload a file into the messaging-channel thread a run reports to — a demo recording, for example — so it renders natively there (Slack plays video uploads inline).
Why the run is in its state, when there is something to say.
runs[].created_at
string
Yes
ISO 8601.
runs[].state_changed_at
string
Yes
ISO 8601 of the last transition.
total
integer
Yes
list_agent_runs
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
agent_ids
string[]
Yes
limit
integer
No
Output
Field
Type
Required
Description
runs
object[]
Yes
runs[].task_id
string
Yes
runs[].title
string
Yes
runs[].prompt
string
Yes
runs[].state
string
Yes
runs[].status_reason
string | null
Yes
runs[].started_at
string
Yes
runs[].ended_at
string | null
Yes
runs[].state_changed_at
string | null
Yes
runs[].hard_deadline_at
string
Yes
When the runtime will be forcefully stopped.
runs[].last_model_activity_at
string | null
Yes
Most recent model request attributed to this run.
runs[].attention_state
"input_required" | "auth_required" | null
Yes
Native runtime signal that the live process needs user attention.
runs[].agent
object
Yes
runs[].agent.id
string
Yes
runs[].agent.name
string
Yes
runs[].agent.icon
string | null
Yes
runs[].requester
object
Yes
runs[].requester.kind
string
Yes
runs[].requester.id
string
Yes
runs[].requester.name
string | null
Yes
runs[].run_url
string
Yes
runs[].thread
object | null
Yes
runs[].thread.provider
string
Yes
runs[].thread.channel_id
string
Yes
runs[].thread.channel_name
string | null
Yes
runs[].thread.thread_id
string
Yes
runs[].thread.url
string | null
Yes
summary
object
Yes
summary.total
integer
Yes
summary.active
integer
Yes
summary.by_state
object
Yes
steer_run
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
task_id
string
Yes
message
string
Yes
cancel_run
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
task_id
string
Yes
post_run_file
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
task_id
string
Yes
filename
string
Yes
content_base64
string
Yes
comment
string
No
Code Sandbox
These tools are served only when the code runtime is enabled — set ARCHESTRA_CODE_RUNTIME_DAGGER_RUNNER_HOST, or ARCHESTRA_CODE_RUNTIME_ENABLED=true together with an orchestrator kubeconfig. Without it they do not appear in tools/list. The Code Sandbox page covers what the runtime is and how an agent uses it.
Tool
Description
Required RBAC Permission
run_command
Execute a shell command in the conversation's sandbox (Debian, working dir /home/sandbox).
sandbox:execute
download_file
Copy a file that already exists at a path in the conversation's sandbox into the conversation's persistent files.
sandbox:execute
upload_file
Place a file into the conversation's sandbox at a path, from a chat attachment, inline base64, inline text, or one of your persistent files.
sandbox:execute
run_command
Required RBAC permission: sandbox:execute
Input
Parameter
Type
Required
Description
command
string
Yes
Shell command to execute (bash). Runs in the sandbox's working directory (or cwd when provided). Returns text output only — use download_file for generated files.
cwd
string
No
Optional absolute path inside the container. Defaults to the sandbox's working directory (/home/sandbox).
timeoutSeconds
integer
No
Optional wall-clock limit in seconds, capped at the deployment maximum.
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
commandId
string
Yes
sandboxId
string
Yes
command
string
Yes
cwd
string | null
Yes
stdout
string
Yes
stderr
string
Yes
exitCode
number
Yes
durationMs
number
Yes
timedOut
boolean
Yes
truncated
boolean
Yes
binaryStripped
boolean
Yes
True when NUL bytes were stripped from stdout/stderr before storage.
stagingNotices
string[]
Yes
Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox.
download_file
Required RBAC permission: sandbox:execute
Input
Parameter
Type
Required
Description
path
string
Yes
Path to the file inside the container — absolute, or relative to the sandbox's working directory.
mimeType
string
No
Optional MIME type recorded with the file. Sniffed from the bytes when omitted.
overwrite
boolean
No
Replace an existing same-named persistent file in place, keeping its id. Default false errors if the name is already taken.
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
fileId
string
Yes
sandboxId
string
Yes
path
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
stagingNotices
string[]
Yes
Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox.
overwritten
boolean
Yes
True when an existing same-named file was replaced in place.
upload_file
Required RBAC permission: sandbox:execute
Input
Parameter
Type
Required
Description
path
string
Yes
Destination path inside the container — absolute under /skills or /home/sandbox, or relative to the sandbox's working directory.
source
object | object | object | object
Yes
Where the file bytes come from. One of four shapes, each tagged by a type: a chat attachment ({"type":"chat_attachment","attachmentId"|"filename":...}), inline base64 ({"type":"base64","dataBase64":...}), inline text ({"type":"text","text":"print(1)"}), or a file from the user's persistent files ({"type":"my_file","filename":...}, found via search_files). Use this to place input bytes; to create a file the sandbox will then run or read, write it with run_command instead.
source.type
string
Yes
source.attachmentId
string
No
Id of an attachment in the current conversation. The bytes are copied directly and never enter your context.
source.filename
string
No
Original filename of an attachment in this conversation (when you have no id). If the same name was attached more than once, the newest one wins.
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
uploadId
string
Yes
sandboxId
string
Yes
path
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
Files
These tools are served only when the code runtime is enabled — set ARCHESTRA_CODE_RUNTIME_DAGGER_RUNNER_HOST, or ARCHESTRA_CODE_RUNTIME_ENABLED=true together with an orchestrator kubeconfig. Without it they do not appear in tools/list. They operate on the conversation's persistent files, not inside the sandbox container.
Tool
Description
Required RBAC Permission
search_files
List or search the conversation's persistent files.
file:manage
read_file
Read a persistent file directly, without copying it into the sandbox.
file:manage
save_file
Write bytes you are providing inline in this call — text or base64 included in the arguments — to the conversation's persistent files.
file:manage
edit_file
Edit an existing persistent file by replacing a snippet, keeping its id and filename.
file:manage
delete_file
Permanently delete a persistent file, identified by id (from search_files / save_file) or by filename.
file:manage
copy_file
Exchange a file between this chat and the app the user has open: copy a chat/project file or a chat attachment INTO the open app's file store (so the app can load it), or copy a file OUT of the app...
file:manage
search_files
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
query
string
No
Case-insensitive substring matched against filenames only. Omit it (or pass empty) to list the files (the first 200).
scope
"chat" | "app"
No
"chat" (default) = this chat's files; "app" = the files of the app the user has open, which is how you find what the app has produced before copying one out with copy_file.
project_id
string
No
Read this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be read. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
files
object[]
Yes
files[].id
string | null
Yes
Row id (UUID), or null for a hand-placed file with no row.
files[].ref
string
Yes
Stable handle for this file — pass it to read_file / upload_file / edit_file / delete_file. Works for hand-placed files too (where id is null).
files[].filename
string
Yes
files[].mimeType
string
Yes
files[].sizeBytes
number
Yes
files[].createdAt
string
Yes
read_file
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
id
string
No
Id or ref of the file to read — the id or ref from search_files, or a fileId from save_file.
filename
string
No
Filename to read instead of id; rejected as ambiguous if more than one file shares the name.
offset
integer
No
1-based line number to start reading from. Defaults to 1.
limit
integer
No
Maximum number of lines to read. Defaults to 2000.
project_id
string
No
Read this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be read. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
kind
"text" | "image"
Yes
text = numbered lines in the text content; image = the file is returned as an inline image block.
fileId
string | null
Yes
The file's id, or null for a hand-placed file with no row.
filename
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
totalLines
number
No
startLine
number
No
returnedLines
number
No
truncated
boolean
No
True when more lines follow the returned window (raise offset to continue).
content
string
No
The returned window's text, WITHOUT the line numbers — the file's own bytes. Present for text reads so a structured consumer (an app via archestra.tools.call, which unwraps to structuredContent and never sees the text block) gets usable content instead of only metadata. The numbered rendering stays in the text output, where line numbers are what makes edit_file addressable.
save_file
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
filename
string
Yes
Plain filename including extension (e.g. "joke.md"). No paths.
content
string
No
UTF-8 text content of the file.
contentBase64
string
No
Base64-encoded binary content.
mimeType
string
No
Optional MIME type. Sniffed from the bytes when omitted.
overwrite
boolean
No
Replace an existing file of the same name in place, keeping its id. Default false errors if the name is already taken.
Output
Field
Type
Required
Description
fileId
string
Yes
filename
string
Yes
projectName
string | null
Yes
Owning project when saved in a project chat; null otherwise.
mimeType
string
Yes
sizeBytes
number
Yes
overwritten
boolean
Yes
True when an existing same-named file was replaced in place.
edit_file
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
id
string
No
Id of the file to edit (from search_files / save_file).
filename
string
No
Filename to edit instead of id; rejected as ambiguous if more than one file shares the name.
old_string
string
Yes
The exact text to replace; must match the file's current content (read it first with read_file). Include enough surrounding context to be unique unless replace_all is set.
new_string
string
Yes
The text to insert in place of old_string.
replace_all
boolean
No
Replace every occurrence of old_string. Default false replaces a single occurrence and errors if old_string is not unique.
Output
Field
Type
Required
Description
fileId
string
Yes
filename
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
replacements
number
Yes
How many occurrences of old_string were replaced.
delete_file
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
id
string
No
Id of the file to delete (from search_files / save_file).
filename
string
No
Filename to delete instead of id; rejected as ambiguous if more than one file shares the name.
Output
Field
Type
Required
Description
fileId
string
Yes
filename
string
Yes
deleted
boolean
Yes
copy_file
Required RBAC permission: file:manage
Input
Parameter
Type
Required
Description
from
object | object | object
Yes
Where the bytes come from: {"type":"chat_file","id"|"filename"} | {"type":"chat_attachment","attachmentId"|"filename"} | {"type":"app_file","id"|"filename"}.
from.type
string
Yes
from.id
string
No
File id from search_files.
from.filename
string
No
Filename instead of id; ambiguous names rejected.
to
object
Yes
Where the copy lands.
to.scope
"chat" | "app"
Yes
"app" = the open app's per-viewer store; "chat" = this chat's files (the project's files when this chat belongs to a project).
to.filename
string
No
Destination filename; defaults to the source's name. Plain filename, no paths.
to.overwrite
boolean
No
Replace an existing same-named destination file in place. Default false: a duplicate name is an error.
Output
Field
Type
Required
Description
fileId
string
Yes
Id of the copy at the destination.
filename
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
destination
"conversation" | "project" | "app"
Yes
The scope the copy landed in.
overwritten
boolean
Yes
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 or labels — use it to find an app's id.
app:read
list_app_versions
List the immutable versions of an app, newest first, without returning their HTML.
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
restore_app_version
Restore a historical app version directly on the server as a new head version.
app:update
edit_app
The single path for any change to an app's HTML: pass edits for targeted str_replace changes, imageReplacements to replace embedded images from chat attachments without sending base64 through the m...
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
set_app_labels
Replace an app's labels with exactly the set you pass ([] clears them).
app:update
set_app_lock
Lock or unlock an app.
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.
Optional display icon for the app, as a single emoji character (e.g. "📊") chosen to suit what the app does. Omitted leaves the app with the generic app glyph.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
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
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
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
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
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
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
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. Each whitespace-separated word must appear in the name or description, in any order — so a remembered name matches even when its word order or punctuation differs from how the app was saved.
labels
object[]
No
Filter by labels. AND across keys, OR within the values given for the same key.
labels[].key
string
Yes
labels[].value
string
Yes
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[].labels
object[]
Yes
Key-value labels for organization/categorization.
apps[].labels[].key
string
Yes
The label key.
apps[].labels[].value
string
Yes
The label value.
apps[].warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
list_app_versions
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
Output
Field
Type
Required
Description
appId
string
Yes
latestVersion
number
Yes
versions
object[]
Yes
versions[].version
number
Yes
versions[].createdAt
string
Yes
versions[].current
boolean
Yes
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
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
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.
offset
integer
No
Start of the read window as a 0-based character offset (a JavaScript string index / UTF-16 code unit) into the stored HTML — character-based, not line-based, since minified HTML can be one enormous line. Defaults to 0. An offset past the end returns an empty window, not an error. A window never splits a character in half: its edges shift by one unit when they would.
limit
integer
No
Maximum number of characters to return, starting at offset. Omitted reads to the end of the document; 0 returns no content, just the size metadata.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
scope
"personal" | "team" | "org"
Yes
version
number
Yes
byteSize
number
Yes
UTF-8 byte size of the full stored HTML (never the window's).
totalChars
number
Yes
Total character length of the full stored HTML.
offset
number
Yes
Effective 0-based character offset of the returned window (0 for a full read; clamped to the end when past it).
hasMore
boolean
Yes
True when the document continues past the returned window.
html
string
Yes
The stored HTML, pre-injection (no SDK/base CSS) — the requested character window when offset/limit was passed.
restore_app_version
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
version
integer
Yes
The historical version to restore.
baseVersion
integer
Yes
The current head version. This prevents overwriting a newer edit that landed after the rollback was requested.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
edit_app
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
baseVersion
integer
Yes
The version this edit is based on — the one named by read_app or the latest scaffold_app/edit_app result. Always report the version you actually built the edit from. When the head has moved past it (another conversation edited the app), your edit is treated as a delta from that base and merged with the newer changes; if the regions overlap, the call fails with the head's conflicting content to incorporate.
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 exactly one edit mode.
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 exactly one edit mode.
replacementHtmlSource
object
No
Like replacementHtml, but the document is read server-side from a file you already saved instead of being written out here — use this when the HTML already exists as a file (assembled in the sandbox, or attached to the chat) so its bytes never have to be reproduced as tool arguments. The file must be UTF-8 text and is subject to the same size limit as any other document. Reads whatever the file holds at call time. Pass exactly one edit mode.
replacementHtmlSource.fileId
string
Yes
Id of a saved file whose bytes become the document, as returned by download_file, save_file, or search_files.
imageReplacements
object[]
No
Replace one or more image URLs with the most recently attached image. Pass short surrounding anchors only: the server reads the newest attachment bytes, builds the data URL, and replaces everything between the anchors. Never put attachment ids, filenames, paths, or old/new base64 in edits/tool arguments. The batch is atomic. Pass exactly one edit mode.
imageReplacements[].before_str
string
Yes
Exact short HTML ending with the opening quote immediately before the existing image URL or data URL (for example <img src="). It must occur exactly once; include nearby id/class context when needed to disambiguate.
imageReplacements[].after_str
string
Yes
Exact short HTML starting with the matching closing quote immediately after the existing image URL or data URL (for example " alt="Issue tracker"). The text between before_str and after_str is replaced server-side.
imageReplacements[].source
object
Yes
The most recently attached image in this conversation. Its bytes are read and encoded server-side; never read or base64-encode the attachment yourself.
imageReplacements[].source.type
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
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.
set_app_labels
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose labels to set.
labels
object[]
Yes
Key-value labels to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all. One value per key; a repeated key keeps the last one.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
labels
object[]
Yes
The app's labels after this call.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
set_app_lock
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
locked
boolean
Yes
true locks the app against all modification; false unlocks it (only on the user's direct request).
Output
Field
Type
Required
Description
id
string
Yes
locked
boolean
Yes
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).
