The Archestra MCP Server is built into every deployment and needs no installation. Its tools let an agent manage agents, MCP servers, policies, and knowledge, build apps, and run code in the sandbox. Every tool name starts with archestra__. This page lists tools by their short name.
Permissions. Each tool requires the RBAC permission in the last column of its table. tools/list shows a user only the tools their role allows; a user without knowledgeSource:create, for example, does not see create_knowledge_base. A tool marked † has an extra condition, described in its entry.
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.
Chat
Tool
Description
Required RBAC Permission
todo_write
Write todos to the current conversation.
None (no additional RBAC permission required)
ask_user
Ask the user to pick from a short list of options.
None (no additional RBAC permission required)
todo_write
Required RBAC permission: None (no additional RBAC permission required)
Input
Parameter
Type
Required
Description
todos
object[]
Yes
Array of todo items to write to the conversation.
todos[].id
integer
Yes
Unique identifier for the todo item.
todos[].content
string
Yes
The content or description of the todo item.
todos[].status
"pending" | "in_progress" | "completed"
Yes
The current status of the todo item.
Output
Field
Type
Required
Description
success
true
Yes
Whether the write succeeded.
todoCount
integer
Yes
How many todo items were written.
ask_user
Required RBAC permission: None (no additional RBAC permission required)
Input
Parameter
Type
Required
Description
question
string
Yes
The question shown above the options.
header
string
No
A very short label shown as the question's tab, e.g. 'Visibility'.
options
object[]
Yes
The options the user can pick. Labels must be unique.
options[].label
string
Yes
The option shown to the user.
options[].description
string
No
Optional extra detail shown next to the option.
allowMultiple
boolean
No
When true, the user may select more than one option. Defaults to false (exactly one).
remedy_offer_ids
string[]
No
Exact offer IDs from the blocked ruling that this question asks the user to decide: a review execute_remedy_plan requires, or a plan that would prevent what the user asked for. Say in the question what it would prevent. Omit for ordinary questions.
Output
Field
Type
Required
Description
action
"accept" | "decline" | "cancel"
Yes
Whether the choice form was submitted, declined, or canceled.
selected
string[]
Yes
The labels the user selected. Empty when declined or canceled.
timedOut
boolean
No
True when the question expired without an answer.
Tool Discovery
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).
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.
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: update on the skill (granted per item)
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: update on the skill (granted per item)
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.
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.
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...
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
Use 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 used. 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).
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
Use 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 used. 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.
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.
project_id
string
No
Use 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 used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
fileId
string
Yes
filename
string
Yes
projectName
string | null
Yes
Owning project when saved into a project; null otherwise.
mimeType
string
Yes
sizeBytes
number
Yes
overwritten
boolean
Yes
True when an existing same-named file was replaced in place.
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.
project_id
string
No
Use 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 used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
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.
project_id
string
No
Use 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 used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Where the bytes come from: {"type":"chat_file","id"|"filename"} | {"type":"chat_attachment","attachmentId"|"filename"} | {"type":"app_file","id"|"filename"}.
from.type
"chat_file" | "chat_attachment" | "app_file"
Yes
from.id
string
No
When type="chat_file": File id from search_files. When type="app_file": File id in the app's store.
from.filename
string
No
When type="chat_file": Filename instead of id; ambiguous names rejected. When type="chat_attachment": 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. When type="app_file": Filename instead of id.
from.attachmentId
string
No
Id of an attachment uploaded to THIS conversation.
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.
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.
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.
Destination path inside the container — absolute under /skills or /home/sandbox, or relative to the sandbox's working directory.
source
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
"chat_attachment" | "base64" | "text" | "my_file"
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
When type="chat_attachment": 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. When type="my_file": Exact filename of a persistent file (when you have no id).
source.dataBase64
string
When type="base64"
Base64-encoded file bytes.
source.mimeType
string
No
source.originalName
string
No
source.text
string
When type="text"
UTF-8 text content of the file.
source.id
string
No
Id or ref of a persistent file, as returned by search_files (id for stored files, ref for hand-placed ones).
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
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.
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.
Restore a historical app version directly on the server as a new head version.
update on the app (granted per item)
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...
update on the app (granted per item)
set_app_tools
Replace an existing app's assigned upstream tools with exactly the set you pass (the full desired list; [] clears all).
update on the app (granted per item)
set_app_labels
Replace an app's labels with exactly the set you pass ([] clears them).
update on the app (granted per item)
set_app_lock
Lock or unlock an app.
update on the app (granted per item)
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...
Share an app by granting read and use access to specific teams (scope: team, teams: names or IDs) or the whole organization (scope: org).
manage-permissions on the app (granted per item)
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.
update on the app (granted per item)
get_app_diagnostics
Check how the app's current version rendered for you.
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.
project_id
string
No
Link the new app into this project (from list_projects) so it is listed with the project's files. You need access to the project. Omitted creates a standalone app.
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: update on the app (granted per item)
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.
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.
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: update on the app (granted per item)
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: update on the app (granted per item)
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
"chat_attachment"
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: update on the app (granted per item)
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: update on the app (granted per item)
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: update on the app (granted per item)
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).
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: manage-permissions on the app (granted per item)
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: update on the app (granted per item)
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).
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: update on the app (granted per item)
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.
Read one project's context in a single call: its metadata, its instructions (the instructions.md that steers every chat in the project), the files it owns, and the apps linked into it that you ca...
List the scheduled agent triggers the caller can see: which agent each one runs, its cron expression and timezone, whether it is enabled, and when it last fired.
List a scheduled task's run history, newest first: whether each run was due or manual, how it ended, when it started and completed, its failure text, and the chat conversation holding its transcript.
Additional access requirement: Returns only projects the caller owns or that are shared with them. Oversight of every project (a * grant) 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.
Additional access requirement: Readable only for projects the caller owns or that are shared with them. Oversight of every project (a * grant) 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.
apps
object[]
Yes
Apps linked into the project that you can open. Read or edit one with the app tools, passing this id.
Additional access requirement: Requires a user token. Only the schedule actor or a scheduled-task administrator can change or run it. Project membership alone permits reading.
Input
Parameter
Type
Required
Description
name
string
No
Name of the scheduled task.
project_id
string
No
Project containing the scheduled task.
agent_id
string
No
Agent to run. Defaults to the project's agent, then the organization default.
cron_expression
string
No
Cron expression, for example 0 9 * * 1-5.
timezone
string
No
IANA timezone, for example America/Toronto.
message_template
string
No
Prompt sent to the agent on each run.
enabled
boolean
No
Whether the schedule is enabled. Defaults to true on creation.
schedule_trigger_id
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or a scheduled-task administrator can change or run it. Project membership alone permits reading.
Additional access requirement: Requires a user token. Only the schedule actor or a scheduled-task administrator can change or run it. Project membership alone permits reading.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to enable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or a scheduled-task administrator can change or run it. Project membership alone permits reading.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to disable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or a scheduled-task administrator can change or run it. Project membership alone permits reading.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to run.
Output
Field
Type
Required
Description
id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
trigger_id
string
Yes
Id of the schedule this run belongs to.
run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
started_at
string | null
Yes
ISO 8601 timestamp the run started.
completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
created_at
string
Yes
ISO 8601 creation timestamp.
Agent Runtime
Tool
Description
Required RBAC Permission
delete_workspace
Permanently delete a retained runtime workspace and all of its files.
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).
What the agent should do, including handoff context and acceptance criteria.
attachments
object[]
No
Input files staged before the first turn. For repository work, include a patch for uncommitted changes and identify the base commit in message. Never include credentials.
Exactly one credential to transfer. Never include more than the task needs.
environment[].key
string
Yes
Environment variable name, e.g. AWS_SECRET_ACCESS_KEY.
environment[].type
"secret"
Yes
Always 'secret'. Marks the value for redaction in logs.
environment[].value
string
No
The credential value to transfer. OMIT IT to declare the credential without a value and get back a link the person opens to paste it themselves — the value then never enters your context. Send a value only when the person asked you to move one you already hold.
label
string
No
Human-readable name shown in the Agent's credential list. Defaults to the key.
Output
Field
Type
Required
Description
key
string
Yes
The environment variable the value is stored under.
scope
"personal"
Yes
Who the value applies to. Always personal to the calling user.
declarationCreated
boolean
Yes
Whether this call declared the credential on the Agent.
valueStored
boolean
Yes
Whether a value is now stored. False means the credential is declared and still empty.
url
string | null
Yes
Where the person pastes the value. Null when this call already stored one.
availability
string
Yes
When a run can read the value, in plain words.
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.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
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.
Filter by a configured provider key, or organization-default for agents with no pinned key or model.
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[].executionMode
"runtime" | "foreground"
Yes
Runtime agents retain a workspace and support steering; foreground agents do not.
agents[].description
string | null
Yes
The agent description, if any.
agents[].resolvedLlmProviderKeyName
string | null
Yes
The configured provider-key name, or null when unconfigured.
agents[].resolvedLlmModelName
string | null
Yes
The configured model name, or null when unconfigured.
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: update on the agent (granted per item)
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.
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.
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: update on the agent (granted per item)
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: update on the agent (granted per item)
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: update on the agent (granted per item)
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
true
Yes
id
string
Yes
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.
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.
Type of the knowledge connector (for example jira, confluence, or google_drive).
config
object
Yes
Provider-specific configuration object.
description
string | null
No
Description of the knowledge connector.
sync_permissions_from_source
boolean
No
Mirror each document's access control from the source, so a query only returns what the caller could open there. Requires an enterprise license and a connector type that supports it.
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...
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.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
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.
List the external consults OpenAPPA recorded for one session, newest first: every annotator, context provider, authority, sanitizer and audience source it asked, with the outcome, the HTTP status, ...
Copy the OpenAPPA configuration template into a private GitHub repository, seed it with the current policy and battery declarations, and start GitHub sync.
The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits.
edits
object[] | null
No
Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line.
The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits.
edits
object[] | null
No
Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line.
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.
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.
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.
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.
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.
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.
The coding client the payload targets: claude-code, codex, copilot-cli, or cursor.
supportedPlatforms
string[]
No
Operating systems the payload supports.
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.
Disabled plugins are left out of future setup commands; already-installed copies are unaffected.
supportedPlatforms
string[]
No
Operating systems the payload supports.
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.
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.
