Tools Reference

Complete list of all MCP tools exposed by the SOAT server, grouped by module. Each tool name maps directly to the MCP tools/call method name.

Actors

See Actors module docs for permissions and data model.

Tool	Description
list-actors	Returns all actors the caller has access to. If projectId is provided, returns only actors in that project. project keys are scoped to a single project automatically. JWT users without projectId receive actors across all their accessible projects.
create-actor	Creates a new actor. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.
get-actor	Returns an actor by its ID
delete-actor	Deletes an actor by its ID
update-actor	Updates an actor's properties
get-actor-tags	Returns all tags attached to the actor
replace-actor-tags	Replaces all tags on the actor with the provided tags (not merged)
merge-actor-tags	Merges provided tags with existing tags (existing tags are preserved unless overridden)

Agents

See Agents module docs for permissions and data model.

Tool	Description
create-agent	Creates a new agent bound to an AI provider.
list-agents	Returns all agents in the project.
get-agent	Returns a single agent by ID.
update-agent	Updates an existing agent. Identical to PATCH — both perform partial updates.
patch-agent	Partially updates an existing agent. Identical to PUT — both perform partial updates.
delete-agent	Deletes an agent by ID. Fails with 409 if the agent has dependent generations or traces, unless force=true is passed, in which case those generations and traces are deleted along with the agent.
create-agent-generation	Sends messages to the agent, resolves its tools, and runs the AI model loop. Supports streaming via stream: true. Client tools pause the generation and return requires_action.
submit-agent-tool-outputs	Resumes a generation that was paused due to client tool calls. Provide tool outputs for each pending tool call.

AI Providers

See AI Providers module docs for permissions and data model.

Tool	Description
list-ai-providers	Returns a list of AI provider configurations for a project
create-ai-provider	Creates a new LLM provider configuration
get-ai-provider	Returns a specific AI provider configuration
update-ai-provider	Updates an AI provider configuration
delete-ai-provider	Deletes an AI provider configuration
get-ai-provider-prices	Returns the per-provider price overrides for this AI provider instance. An override prices this specific provider (e.g. an enterprise-negotiated rate or a gateway with markup) and wins over the global default at cost time. Authorized by the caller's access to the provider's project — so, unlike the global price book, a project's own overrides are visible here.
update-ai-provider-prices	Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. effective_from must be in the future — past prices are immutable, so ship corrections as new future-dated rows.

API Keys

See API Keys module docs for permissions and data model.

Tool	Description
list-api-keys	Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - API key: returns only API keys scoped to the key's project.
create-api-key	Creates a new API key for the authenticated user. - project_id is required: every key is scoped to exactly one project. - If policy_ids is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions, confined to the key's project.
get-api-key	Returns details of an API key. Only the owner or an admin can access it.
update-api-key	Updates an API key's name, project scope, or policies. The project scope can be changed to another project but never cleared. Only the owner or an admin can update it.
delete-api-key	Deletes an API key. Only the owner or an admin can delete it.

Chats

See Chats module docs for permissions and data model.

Tool	Description
create-chat	Creates a new chat resource bound to an AI provider.
list-chats	Returns all chats in the project.
get-chat	Returns a single chat by ID.
delete-chat	Deletes a chat by ID.
create-chat-completion-for-chat	Runs a completion using the AI provider and settings stored in the chat. Pass stream: true for SSE streaming. A system message in messages overrides the chat's stored system message for this call only. Messages may use documentId instead of content.
create-chat-completion	OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's POST /v1/chat/completions path so an OpenAI SDK can target it by base URL alone. Resolves the AI provider from ai_provider_id, decrypts its secret, and calls the appropriate Vercel AI SDK provider. ai_provider_id is required — there is no server-side model fallback.

Conversations

See Conversations module docs for permissions and data model.

Tool	Description
list-conversations	Returns all conversations the caller has access to. If projectId is provided, returns only conversations in that project. project keys are scoped to a single project automatically.
create-conversation	Creates a new conversation. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.
get-conversation	Returns a conversation by its ID
update-conversation	Updates the status of a conversation
delete-conversation	Deletes a conversation by its ID
list-conversation-messages	Returns all messages (documents) attached to a conversation, ordered by position
add-conversation-message	Creates a document from the message text and attaches it to the conversation at the given position. If position is omitted, it is appended at the end.
generate-conversation-message	Generates the next message using the specified actor's linked agent or chat.
On completed, the reply is persisted as a new ConversationMessage authored
by that actor. On requires_action, nothing is persisted; the caller must
submit tool outputs via the Agents module and re-invoke generate.
remove-conversation-message	Removes a document from a conversation
get-conversation-tags	Returns all tags attached to the conversation
replace-conversation-tags	Replaces all tags on the conversation with the provided tags
merge-conversation-tags	Merges provided tags with existing tags

Discussions

See Discussions module docs for permissions and data model.

Tool	Description
list-discussions	Returns all discussions the caller has access to. If project_id is provided, returns only discussions in that project.
create-discussion	Creates a new discussion config. project keys infer the project from the key's scope; JWT callers must supply project_id.
get-discussion-run	Returns a single discussion run, including its outcome, transcript conversation, and outcome document.
get-discussion	Returns a discussion config with its participants.
update-discussion	Updates a discussion. Providing participants replaces the full set (not merged).
delete-discussion	Deletes a discussion config and its participants.
create-discussion-run	Runs the discussion synchronously over the given topic and returns the completed run, whose outcome inlines the synthesized text. The run's transcript is persisted as a conversation and the outcome as a document.
list-discussion-runs	Returns the run history of a discussion, most recent first.

Documents

See Documents module docs for permissions and data model.

Tool	Description
list-documents	Returns all documents the caller has access to. If projectId is provided, returns only documents in that project. project keys are scoped to a single project automatically. JWT users without projectId receive documents across all their accessible projects.
create-document	Creates a new text document and generates an embedding vector for semantic search. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.
ingest-document	Parses an already-uploaded file and creates one Document split into one or
more embedded chunks. The source format is detected from the file's content
type: PDFs are parsed page-by-page; text/plain and text/markdown files
are read as a single source. How the source is chunked is controlled by
chunk_strategy.
get-document	Returns a document with its text content
delete-document	Deletes a document and its underlying file
update-document	Updates document content, title, path, metadata, or tags. Supplying path moves the document to a new logical path within the project.
get-document-status	Returns a lightweight ingestion status payload for polling — status,
chunk_count, total_pages, and (when failed) error. Unlike
GET /documents/{document_id}, it never returns the assembled chunk
content, so it is cheap to poll on large documents. A document whose
ingestion has stalled (no progress past the configured timeout) is
transitioned to failed with error=INGESTION_TIMEOUT on read.
reingest-document	Re-runs ingestion for an existing document against its already-stored
source file. Existing chunks are discarded and the document is reset to
status=pending before re-processing. Use this to recover a document
stuck in processing/failed or to re-chunk with a different strategy
without re-uploading the file. Async by default (202); pass
?async=false to run synchronously (201).
complete-ingestion-callback	Token-authed callback for a tool converter that deferred conversion by
returning { "status": "pending" } (see the Ingestion Rules module
docs). Not IAM-gated — the external converter is not a SOAT principal,
so it authenticates with the single-use token minted for this
document and ingestion attempt (delivered as callback.token /
embedded in callback.url in the original converter invocation).
Accepted only while the document is still awaiting that exact
attempt; rejected with 409 if the attempt already completed, timed
out, or was superseded by a re-ingest.
get-document-tags	Returns all tags attached to the document
replace-document-tags	Replaces all tags on the document with the provided tags (not merged)
merge-document-tags	Merges provided tags with existing tags (existing tags are preserved unless overridden)

Embeddings

See Embeddings module docs for permissions and data model.

Tool	Description
create-embeddings	Generates embedding vectors for one or more text inputs using the server's configured embedding model.
Provide input for a single text or inputs for a batch. At least one is required.
Returns embedding when input is used, and embeddings when inputs is used.

Files

See Files module docs for permissions and data model.

Tool	Description
list-files	Returns a list of all stored files
create-file	Creates a new file record in the system
upload-file	Uploads a file to the server and stores it in the configured storage directory
upload-file-base64	Uploads a file to the server using base64-encoded content
create-presigned-url	Creates a short-lived, single-use presigned upload URL — the local-storage equivalent of an S3 presigned URL. The client then uploads the file content directly to the returned upload_url via POST /api/v1/files/upload/{token}, bypassing MCP payload size limits. When the server is configured with SOAT_BASE_URL, upload_url is a fully-qualified absolute URL so MCP agents and other clients can POST to it without knowing the server base URL in advance.
upload-file-with-token	Uploads file content authorized by a single-use token from POST /api/v1/files/presigned-url. No bearer credential is required — the token is the credential. Accepts either multipart/form-data (field file) or JSON with a base64-encoded content field.
get-file	Returns the data and metadata of a specific file
delete-file	Removes a file from the system by ID
download-file	Streams the file content to the client
update-file-metadata	Updates the metadata field of a file
download-file-base64	Returns the file content encoded as base64
get-file-tags	Returns all tags attached to the file
replace-file-tags	Replaces all tags on the file with the provided tags
merge-file-tags	Merges provided tags with existing tags

Formations

See Formations module docs for permissions and data model.

Tool	Description
validate-formation	Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.
plan-formation	Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions.
list-formations	Returns all formation stacks for a project
create-formation	Validates the template, creates the formation record, then provisions all declared resources in dependency order.
get-formation	Returns the formation stack including its current resources.
update-formation	Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.
delete-formation	Deletes the formation stack and all its managed resources in reverse dependency order.
list-formation-events	Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically.

Generations

See Generations module docs for permissions and data model.

Tool	Description
list-generations	Returns generations the caller can access, optionally filtered by agent, trace, and status. Replaces the former per-trace generations endpoint (use the trace_id query filter).
get-generation	Returns a single generation record by ID, including its status and the structured error payload when the generation failed (e.g. because the upstream AI provider returned an error).

Ingestion Rules

See Ingestion Rules module docs for permissions and data model.

Tool	Description
list-ingestion-rules	Returns the ingestion rules for a project
create-ingestion-rule	Creates a rule mapping a content_type glob to a converter. Exactly one of tool_id or agent_id must be set.
get-ingestion-rule	Returns a specific ingestion rule
update-ingestion-rule	Updates fields of an ingestion rule
delete-ingestion-rule	Deletes an ingestion rule

Knowledge

See Knowledge module docs for permissions and data model.

Tool	Description
search-knowledge	Searches across documents and memory entries using semantic search, file paths, document IDs, or memory IDs/tags. At least one of query, document_paths, document_ids, memory_ids, or memory_tags must be provided.

Memories

See Memories module docs for permissions and data model.

Tool	Description
list-memories	Returns a list of memory configurations for a project
create-memory	Creates a new memory configuration in a project
get-memory	Returns a single memory configuration by ID
update-memory	Updates an existing memory configuration
delete-memory	Deletes a memory configuration

MemoryEntries

See MemoryEntries module docs for permissions and data model.

Tool	Description
list-memory-entries	Returns all entries in a memory container
create-memory-entry	Creates a new entry in the specified memory container. Automatically generates an embedding for semantic search.
get-memory-entry	Returns a single memory entry by ID
update-memory-entry	Updates an existing memory entry. Regenerates the embedding if content changes.
delete-memory-entry	Deletes a memory entry

Orchestrations

See Orchestrations module docs for permissions and data model.

Tool	Description
create-orchestration	Creates a new orchestration workflow definition in the project.
list-orchestrations	Returns orchestrations accessible to the caller.
validate-orchestration	Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every input_mapping {"var": "..."} reference resolves to a state key written by an upstream node or seeded by input_schema. Returns blocking errors and non-blocking warnings (e.g. a state key only written on a conditional branch). The same errors checks are enforced on create and update, which fail with 400 when any error is present.
get-orchestration	Returns the orchestration with nodes and edges.
update-orchestration	Partially updates an orchestration definition.
delete-orchestration	Deletes an orchestration definition and all its runs.
start-orchestration-run	Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "running" and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state (the legacy synchronous behaviour).
list-orchestration-runs	Returns orchestration runs the caller can access, optionally filtered by orchestration.
cancel-orchestration-run	Cancels a run that has not yet reached a terminal state.
submit-human-input	Provides human input to a run that is awaiting_input at a human node.
resume-orchestration-run	Resumes an awaiting_input orchestration run from its last checkpoint.
get-orchestration-run	Returns the status, state, and artifacts of a specific run.

Policies

See Policies module docs for permissions and data model.

Tool	Description
list-policies	Returns global policies. Requires admin role. Pass user_id to list only the policies attached to that user (replaces the former per-user policies endpoint).
create-policy	Creates a new global policy. Requires admin role.
get-policy	Returns details of a specific policy. Requires admin role.
update-policy	Updates an existing global policy. Requires admin role.
delete-policy	Deletes a global policy. Requires admin role.

Projects

See Projects module docs for permissions and data model.

Tool	Description
list-projects	Lists projects accessible to the caller. - JWT admin: returns all projects. - JWT regular user: returns only projects granted by the user's policies. - API key scoped to a project: returns only that project.
create-project	Creates a new project. Requires admin role.
get-project	Returns details of a specific project.
update-project	Updates a project's name. Requires admin role.
delete-project	Deletes a project. Requires admin role. Fails with 409 if the project has any dependent resources (agents, ai providers, tools, conversations, chats, formations, memories, actors, webhooks, secrets, sessions, files, traces, generations, orchestrations, etc.), unless force=true is passed, in which case those resources are deleted along with the project.
get-project-prices	Returns the project's per-provider-slug price rows — the middle pricing tier that covers every one of the project's instances of a given provider slug. At cost time a per-provider-instance override wins over these, and these win over the global default. Authorized by the caller's access to the project.
update-project-prices	Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. effective_from must be in the future — past prices are immutable, so ship corrections as new future-dated rows.

Secrets

See Secrets module docs for permissions and data model.

Tool	Description
list-secrets	Returns a list of secrets for a project
create-secret	Creates a new encrypted secret in a project
get-secret	Returns a specific secret
update-secret	Updates a secret's name and/or value
delete-secret	Deletes a secret

Sessions

See Sessions module docs for permissions and data model.

Tool	Description
create-session	Creates a new session for the specified agent. Internally creates a conversation and two actors (agent + user) so the caller only needs this single call to start interacting with the agent.
list-sessions	Returns sessions the caller can access, optionally filtered by agent, actor and status.
get-session	Returns details of a single session.
update-session	Updates the session name and/or status.
delete-session	Deletes the session and its underlying conversation and messages. The session's actor is not deleted. Generations and traces produced by the session are not deleted either, since they are not linked to the session or conversation.
add-session-message	Saves a user message to the session. When autoGenerate is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response mirrors GenerateSessionResponse. Otherwise returns the saved user message.
generate-session-response	Triggers the agent to generate a response based on the current conversation. Returns the assistant reply or a requires_action status if the agent needs client tool outputs. Pass ?async=true for a 202 accepted response when you do not need to wait for the result.
submit-session-tool-outputs	Submits client tool outputs for a generation that returned requires_action. The agent continues its loop and returns the final or next requires_action result.
get-session-tags	Returns the session's tags object.
replace-session-tags	Replaces all tags on the session.
merge-session-tags	Merges the provided tags into the session's existing tags.

Tools

See Tools module docs for permissions and data model.

Tool	Description
create-tool	Creates a new tool in the project.
list-tools	Returns all tools in the project.
get-tool	Returns a single tool by ID.
update-tool	Updates an existing tool.
delete-tool	Deletes a tool by ID.
call-tool	Directly invokes a tool and returns its output. Supported for http, soat, mcp, and pipeline tools. client tools cannot be invoked server-side and will return 422. A pipeline tool runs its declared steps in order and returns the mapped output (or the last step's output); action is ignored and input is the pipeline input.
For soat and mcp tools the action field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For http tools action is ignored. When a soat or mcp tool declares an actions allowlist, an action outside it is rejected with 400 VALIDATION_FAILED ("not available on this tool") before any outbound request is made.
preset_parameters stored on the tool are merged with the caller-supplied input before execution; preset keys take lower precedence.

Traces

See Traces module docs for permissions and data model.

Tool	Description
list-traces	Returns a paginated list of execution traces for the project.
get-trace	Returns a single trace by ID.
get-trace-tree	Returns the full execution tree rooted at the given trace (or its root if the given trace is a child). Each node represents one agent's execution session. The children array contains traces triggered by sub-agent tool calls from that trace.

Triggers

See Triggers module docs for permissions and data model.

Tool	Description
list-triggers	Lists triggers. Filter by project, starter type, or target type.
create-trigger	Creates a new trigger for a project
get-trigger	Retrieves the details of a specific trigger
update-trigger	Updates an existing trigger's configuration. The type is immutable.
delete-trigger	Deletes a trigger
fire-trigger	Fires a trigger synchronously and returns the terminal firing record.
get-trigger-secret	Retrieves the signing secret for a webhook trigger
rotate-trigger-secret	Rotates the signing secret for a webhook trigger
list-trigger-firings	Lists firings for a trigger (trigger_id is required).
get-trigger-firing	Retrieves the details of a specific trigger firing

Usage

See Usage module docs for permissions and data model.

Tool	Description
list-usage-meters	Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
get-usage-receipt	Returns a billing receipt for a completed generation: per-model line items (tokens, the price-book version that priced them, and cost) plus totals.
get-price-book	Returns the global price book — the versioned per-provider/model unit prices used to compute usage cost at write time. Readable by any authenticated user.
upsert-price-book	Upserts price rows keyed on (provider, model, effective_from). Admin only. effective_from must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.

Users

See Users module docs for permissions and data model.

Tool	Description
get-current-user	Returns the profile of the currently authenticated user
list-users	Returns a list of all users
create-user	Creates a new user in the system
get-user	Returns the data of a specific user
delete-user	Deletes a specific user
bootstrap-user	Creates the first admin user. Returns 409 if any user already exists.
login-user	Authenticates a user and returns a JWT token
attach-user-policies	Replaces the user's policy list with the provided policy IDs. Requires admin role.

Webhooks

See Webhooks module docs for permissions and data model.

Tool	Description
list-webhooks	Lists webhooks. Use the project_id query parameter to filter by project.
create-webhook	Creates a new webhook for a project
get-webhook	Retrieves the details of a specific webhook
update-webhook	Updates an existing webhook's configuration
delete-webhook	Deletes a webhook and stops all event deliveries
list-webhook-deliveries	Lists event deliveries for a webhook (webhook_id is required).
get-webhook-delivery	Retrieves the details of a specific webhook delivery
get-webhook-secret	Retrieves the signing secret for the specified webhook
rotate-webhook-secret	Rotates the secret key for the specified webhook