Skip to main content
An agent calls a tool. Three things have to be true the moment that call leaves the model’s mouth — the tool exists, the agent is allowed to use it, and the call is recorded. The Tool Registry is the system that makes those three things true together. Every tool. Every dispatch site. Every time. A tool is a runtime primitive an agent invokes — read a file, post a message, query org chart, run a command in a sandbox. The Tool Registry is the platform-wide system that decides which tools exist, who can use them, how each call is wrapped, and how every invocation is recorded. It is the answer to what is the agent allowed to do, right now, on this turn? Two layers compose into one registry:
  • Code tools declared in the code tool-set registry (TOOL_SETS) with metadata in TOOL_META and TOOL_SET_MEMBERS.
  • Database tools stored as rows in the toolDefinitions table — external HTTP integrations, MCP servers, factory-bound tools.
Both layers are reconciled into a single materialized catalog that the Forge Console renders at /platform/tools and that every dispatch reads through agent composition.

The four moves

Four moves, one chokepoint. Every tool that reaches an agent’s tools map flowed through these stages — there is no side door.

Register

A platform-shipped tool is added by:
  1. Writing the tool, wrapped in the secured-tool wrapper, in its domain’s tool module.
  2. Listing it under a tool-set name in TOOL_SETS.
  3. Recording its governance metadata in TOOL_META and its membership in TOOL_SET_MEMBERS.
Every tool also carries a data-and-effect declaration. Code tools and external manifests author whether they touch sensitive data. A code tool also declares its effect class in code: 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_META and TOOL_SET_MEMBERS becomes (or refreshes) a toolDefinitions row with source.type = "code".
  • Tools no longer present in the code registry are soft-deprecated (status: "deprecated") rather than deleted — preserving audit history.
  • requiresSandbox is propagated from TOOL_META onto each row so dispatch can decide whether the turn needs a Vercel Sandbox VM.
  • Dispatch-bound tools such as sandbox_action, load_skill, putFile, and getFile are represented in the catalog even though their final authority and bindings are resolved for each dispatch.
After sync, the operator catalog at /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:
  1. The agent’s permitted toolSets[] are intersected with any node-level capability hints.
  2. Each set name is mapped to its TOOL_SETS entry; tools are flattened into a single ToolSet.
  3. Conditional injections happen in-band: load_skill is added for on-demand skills, sandbox_action for resolved sandbox capability, and putFile/getFile for declared and authorized file bindings.
  4. A skill-constraint check wraps tools the active skill’s allowedTools does not permit, so refusals log refused_by_skill_constraint to toolExecutionLog.
  5. Secured tools are bound to the resolved caller identity, and the composed configuration is returned.
The agent then runs. Every invocation that reaches the wrapper hits 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 invokes sandbox.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 own networkPolicy (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 toolDefinitions row and the per-call toolExecutionLog row turns “what tools exist?” and “what did they do?” into queries the operator answers from the Console without leaving the page.
The registry is also the seam where graduated autonomy, budget enforcement, and policy live. Tools carry safety annotations (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_MEMBERS declarations.
  • 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/tools for catalog management, /observe/runs/[runId] for the per-run trace of tool invocations.
Together they answer the only question that matters at dispatch time: given this agent, on this node, in this run — which tools are bound, how are they wrapped, and where do their calls land?
  • 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.