Tool naming
Tools follow anamespace_verb convention: agent_list, mission_run, memory_save, data_query. Namespaces map 1:1 to app resources.
Older verb-first names (list_agents, save_memory, query_data, …) remain permanent aliases: tools/call accepts both spellings, and keys whose stored scopes carry old names keep working. tools/list only ever advertises the canonical names.
Federated (vertical) tools are namespaced with a double underscore: vertical__vertical_card, vertical__vertical_search (server prefix + __ + tool name).
Common parameters
Session bootstrap tools
These two tools are always callable, regardless of the key’s allowlist.whoami
Who am I — identity, role, tenant, departments, missions and the enabled tool surface of this credential. Call this first in every session.
Parameters: none.
Returns:
Example:
get_context
The Operating-Manual context block (high-importance memories + knowledge; rights-aware, token-budgeted) — the same block the in-app chat auto-injects into its system prompt. Over MCP it is pull-only: call once at session start, right after whoami.
Parameters:
Returns: a formatted context block of the highest-importance entries the calling user may read.
Example:
Errors
Responses are JSON-RPC 2.0. Application errors inside a successful tool call come back as an{ "error": "…" } object in the tool result; protocol/authorization errors use JSON-RPC error codes:
Database write failures are mapped to one actionable sentence plus the standard SQLSTATE class (e.g.
Insert failed (23505) — a record with these values already exists.). Raw SQL/schema details are never returned.
Limits
Dry-run
Write tools that supportdry_run:true validate the input, resolve all references and return the would-be effect (e.g. a field-level from → to diff) without persisting anything:
agent_update, agent_schedule_manage, memory_save, skill_create, data_row_save, data_row_create, data_row_update.
Mission runtime controls (mission_cancel, mission_pause, mission_resume, mission_budget_increase) use the confirm pattern instead: calling without confirm:true returns a would preview; only a second call with confirm:true executes.
Router mode (token-lean surface)
A key whose allowlist containsexecute_tool is a router key: tools/list advertises only three meta-tools (plus whoami), and every other allowlist entry becomes an execution target. This cuts client input tokens dramatically for keys with large tool surfaces. Router mode is opt-in per key — it is never part of a default OAuth scope set.
search_tools
Find platform tools by free-text query over name + description (AND-matched terms; empty query lists everything reachable on this key).
Returns: lean rows
{name, write flag, summary}.
Permissions: router keys only.
describe_tool
Full definition of one reachable tool: name, description and the complete inputSchema. Call before execute_tool so inputs are grounded in the real schema.
Permissions: router keys only.
execute_tool
Execute one tool by name with the given input. Dispatches to the exact same implementation as a direct call and enforces the exact same per-key allowlist — the router can never widen a key. Router tools themselves cannot be executed (no recursion); each target still applies its own role gates.
Example: