- Code tools declared in the code tool-set registry (
TOOL_SETS) with metadata inTOOL_METAandTOOL_SET_MEMBERS. - Database tools stored as rows in the
toolDefinitionstable — external HTTP integrations, MCP servers, factory-bound tools.
/platform/tools and that every dispatch reads through agent composition.
The four moves
Four moves, one chokepoint. Every tool that reaches an agent’stools map flowed through these stages — there is no side door.
Register
A platform-shipped tool is added by:- Writing the tool, wrapped in the secured-tool wrapper, in its domain’s tool module.
- Listing it under a tool-set name in
TOOL_SETS. - Recording its governance metadata in
TOOL_METAand its membership inTOOL_SET_MEMBERS.
read, compute (runs a model or judge over what it reads) or write, and whether it sends something out (email, Slack, a GitHub or Google write, an outbound HTTP request, a Sandbox with network egress). The registry sync writes that class; a code tool with no class is declared the strictest case, and a test fails the build for one. For other tools the registry derives the remaining facts from runtime and delivery evidence: only a complete GET-only HTTP surface may floor at read; MCP, Pipedream, mixed-method, and unknown surfaces floor at write.
A read that the hold table passes must keep to its caller, because tenant isolation for reads is the read’s own filter, not a person approving each call. Each such code tool declares a readScope: global (no tenant data), caller (it filters to the builder session’s own draft or the caller’s own org unit), session_draft (held unless it targets the session’s bound draft), acting_principal or unscoped. An acting_principal read returns what the person the agent acts for may read: the person on the turn, else the draft’s author. It returns rows homed in that person’s scopes for the matching list permission (agents:read for agents, workflows:read for procedures, workflows and runs), plus the platform’s own agents and procedures; a call that acts for no person is held (read_scope/acting_principal/hold). The procedure and agent searches, listAgentDefinitions, resolveVendor, getProcedureSpec, getAgentCallers, getSkillCallers and getWorkflowInputContract declare it. awaitSynthesis is session_draft: it passes only for synthesis requests the session’s draft asked for, or was deduplicated onto. An unscoped read returns rows outside the caller’s scope and is held in ad hoc agent work (read_scope/unscoped/hold) until it filters to its caller.
A code tool whose TOOL_META entry sets effectScope: "builder_draft" only reads, or writes only an unpublished draft, such as a synthesizing procedure’s code and test cases or a workflow draft’s nodes. Its control point is publish, so an ad hoc builder agent at the Supervised rung is not held for a person on each edit to the draft its session is bound to (the Workflow Architect’s draft, the Procedure Builder’s procedure). A call that targets any other draft, or that comes from a session with no bound draft, keeps the hold. So does a call on the bound draft whose other arguments point at another draft’s node or schema component, or that renames the procedure draft to a different procedureId. The only exempt tools that name no draft are reads of a shared catalog (tools, primitives, vendors) with no per-user, per-draft, per-request or org-unit-scoped data. Blocks, requiresApproval, approval policies, the permission gate and role allow/deny lists still apply. A tool that publishes, promotes, runs a Sandbox, uses a Credential, or writes shared or live state does not set it and keeps the hold table as written.
A workspace-authored or external tool is added by inserting a row in the toolDefinitions table — typically through the /platform/tools create wizard or a manifest-driven seeder. External tools declare a runtime type (http_api, mcp_remote, mcp_convex, mcp_sandbox) and reference credentials via the toolCredentials system.
The full reference of code tool sets — names, members, and which agents use each — lives in Tool sets.
Audit (the secured-tool wrapper)
The secured-tool wrapper turns a bare tool into a governed call. Every tool the platform considers production-ready is wrapped with it; an unwrapped tool is an explicit, lint-checked exception. The wrapper composes three enforcement stages:
Around all three stages, the wrapper emits structured rows to
toolExecutionLog — started, then completed / failed / refused — with a typed refusalReason enum. Tool calls become first-class auditable events; operators can answer “which tools cost most?” and “which fail most often?” from a single table.
The wrapper also binds the caller’s identity (the agent and its resolved tool sets) at the end of agent composition. Every secured tool knows which agent is on the other end of the call.
Publish
A registry sync materializes the code registry into the tool catalog. It runs each time a release deploys, with these rules:- Every entry in
TOOL_METAandTOOL_SET_MEMBERSbecomes (or refreshes) atoolDefinitionsrow withsource.type = "code". - Tools no longer present in the code registry are soft-deprecated (
status: "deprecated") rather than deleted — preserving audit history. requiresSandboxis propagated fromTOOL_METAonto each row so dispatch can decide whether the turn needs a Vercel Sandbox VM.- Dispatch-bound tools such as
sandbox_action,load_skill,putFile, andgetFileare represented in the catalog even though their final authority and bindings are resolved for each dispatch.
/platform/tools is the single source of truth for both code-shipped and DB-defined tools. Discovery, schema, sandbox config, credentials, “where used”, analytics, and version history all read from this row set.
Invoke
When a dispatch composes its agent:- The agent’s permitted
toolSets[]are intersected with any node-level capability hints. - Each set name is mapped to its
TOOL_SETSentry; tools are flattened into a singleToolSet. - Conditional injections happen in-band:
load_skillis added for on-demand skills,sandbox_actionfor resolved sandbox capability, andputFile/getFilefor declared and authorized file bindings. - A skill-constraint check wraps tools the active skill’s
allowedToolsdoes not permit, so refusals logrefused_by_skill_constrainttotoolExecutionLog. - Secured tools are bound to the resolved caller identity, and the composed configuration is returned.
toolExecutionLog. The catalog at /platform/tools shows usage; per-tool cost rolls up to the token-attribution chains.
Commands — argv-native catalog beneath the tool surface
Tools answer what can the agent ask for? Commands answer what actually runs in the sandbox? The two layers compose: an agent calls a sandbox-backed tool, the tool resolves to a typed command, the command builds an argv array and invokessandbox.runCommand({ cmd, args }) directly. No shell parser between platform and substrate.
This is the Command-as-Capability model. Two tiers ship today:
(Tier 2 — Composite Commands — was deferred indefinitely.)
Per-command governance is real enforcement
Trust Fabric runs a deterministic policy on every command invocation. The decision is a function of three inputs:read-only allows; mutates-fs and network-egress hold below the autonomy threshold; destructive always holds; privileged blocks (only overridable for Tier 3 by an active workerExecGrants row).
Strict mode is unconditional. There is no audit-mode toggle, no wouldHaveBlocked shadow column. Block decisions block. Every invocation lands in governanceAuditLog with the resolved class, the policy decision, and the caller identity.
Network policy applies per command
Tier 1 commands declare their ownnetworkPolicy (deny-all · allow-list · allow-all). sandbox.updateNetworkPolicy() wraps each invocation: the substrate-level policy is the prior, the command’s declared policy is the working state, the prior is restored in a finally block. No cache — the operator decision was to accept the apply/restore latency rather than carry stale-cache correctness risk across turn boundaries.
Operator surfaces
The catalog grows real-usage-driven: operators watch the audit promotion-candidates view, author a Tier 1 entry for recurring patterns, or grant
exec with a documented reason for the rest.
Why a registry, not a list
Three properties only a registry can guarantee:- Single chokepoint. Every tool an agent can call — code-shipped or DB-defined, statically bound or factory-bound — goes through the same composition path and the same secured wrapper. There is no second, undocumented door.
- Default-secure. The secured-tool wrapper is the floor; an unwrapped tool is the opt-out. Adding a new tool requires either being on the explicit allowlist or accepting the wrapper, which means SSRF guards, scope checks, post-call injection scanning, and audit emission come along by default.
- Observable end-to-end. The combination of the materialized
toolDefinitionsrow and the per-calltoolExecutionLogrow turns “what tools exist?” and “what did they do?” into queries the operator answers from the Console without leaving the page.
riskLevel, readOnly, destructive, idempotent, openWorld); skills can declare allowedTools to narrow the surface; the Trust Fabric reads the resolved tool set as part of preflight scope checks. Without the registry, those signals have nowhere to attach.
Where tools live in the system
The registry connects four moving pieces:- Code source — the domain tool modules plus the
TOOL_SETS/TOOL_META/TOOL_SET_MEMBERSdeclarations. - Database state —
toolDefinitions,toolSets,agentToolAssignments,agentToolSetAssignments,toolCredentials,toolSecurityPolicy,toolExecutionLog. - Composition — agent composition plus the per-dispatch finalize step that runs the constraint check and caller binding.
- Operator surface —
/platform/toolsfor catalog management,/observe/runs/[runId]for the per-run trace of tool invocations.
Related
- Tool sets — exhaustive table of every code tool set, its members, and who uses it.
- Skills & Tools — how skills and tools compose into agent capabilities.
- Files and bindings — the per-node factory-bound tool for file outputs.

