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)

AgentFormations

See AgentFormations module docs for permissions and data model.

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

Agents

See Agents module docs for permissions and data model.

Tool	Description
create-agent-tool	Creates a new agent tool in the project.
list-agent-tools	Returns all agent tools in the project.
get-agent-tool	Returns a single agent tool by ID.
update-agent-tool	Updates an existing agent tool.
delete-agent-tool	Deletes an agent tool by ID.
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.
delete-agent	Deletes an agent by ID.
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.
create-agent-actor	Creates a new actor associated with the specified agent

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

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 scoped to a project: returns only API keys scoped to that project.
create-api-key	Creates a new API key for the authenticated user. - If project_id is provided, the key is scoped to that project. - If policy_ids is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - If neither is provided, the key inherits the user's full permissions.
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. 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. 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.
create-chat-actor	Creates a new actor associated with the specified chat

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.
list-conversation-actors	Returns all distinct actors who have sent at least one message in the conversation
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

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.
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-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)

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
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

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

Policies

See Policies module docs for permissions and data model.

Tool	Description
list-policies	Returns a list of all global policies. Requires admin role.
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
create-project	Creates a new project. Requires admin role.
get-project	Returns details of a specific project.
delete-project	Deletes a project. Requires admin role.

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-agent-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-agent-sessions	Returns sessions for the specified agent, optionally filtered by actorId and status.
get-agent-session	Returns details of a single session.
update-session	Updates the session name and/or status.
delete-agent-session	Deletes the session and its underlying conversation and actors.
list-agent-session-messages	Returns messages in the session with simplified roles (user/assistant) instead of raw actor IDs.
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.

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.

Users

See Users module docs for permissions and data model.

Tool	Description
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
get-user-policies	Returns the list of policies attached to a user. Requires admin role.
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 all webhooks configured for the specified project
create-webhook	Creates a new webhook for the specified 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 all event deliveries for a specific webhook
get-webhook-delivery	Retrieves the details of a specific webhook delivery
rotate-webhook-secret	Rotates the secret key for the specified webhook