> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools and skills

> The single source of truth for tools in Forge — what an agent can call, how it's wrapped, and how every invocation is audited.

Last updated 2026-11-11

·
applies to 2026-11-03

·
main

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](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition).

***

## The four moves

Tool Registry lifecycle

<ol aria-label="Tool Registry lifecycle" />

iterate — invoke feeds usage back to the catalog

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](https://docs.gloo.com/forge/reference/tool-sets.md).

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

| Stage | Checks |
| - | - |
| Pre-call | URL allowlist / blocklist (SSRF), header blocklist, caller scope check (does the agent's resolved tool sets include this tool?), sandbox command policy |
| Execute | Original tool handler runs — the actual work |
| Post-call | Scan result for prompt-injection signatures (external-content tools); if a threat is detected, block the result and emit a `SecurityAlertEvent` to `trustFabricEvents` + Slack |

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](https://docs.gloo.com/forge/run/budgets-and-cost.md).

***

## 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 | What it is | Where it lives |
| - | - | - |
| Tier 1 — Catalog Command | A row in `commandDefinitions` with a stable `commandId`, declared `riskClass`, declared `networkPolicy`, a Zod `argsValidator`, an `argvBuilderRef`, and an `idempotent` flag. The mainstream path. | `commandDefinitions` table · `/platform/commands` |
| Tier 3 — sandbox\_action.exec | The free-form bash escape hatch. Every invocation runs through the same governance pipeline as Tier 1, but its `riskClass` is *inferred* from the command string and fails closed to `privileged` when no pattern matches. Friction is intentional. | `governanceAuditLog` · `/platform/commands/audit` |

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

| Input | Source |
| - | - |
| **Risk class** | Declared on the Tier 1 row, or inferred for Tier 3 (`read-only` · `mutates-fs` · `network-egress` · `destructive` · `privileged`). |
| **Rung** | The agent's own rung, read through `autonomyPostureForRung`; here an agent without a rung is treated as Rung 1 Assistive (stored posture `advisory`). Roles carry no rung. |
| **Grants** | `commandGrantsToSkills` for Tier 1 (a skill grants a command, the agent inherits the command at compose time). `workerExecGrants` for Tier 3 (a binary per-worker grant for raw bash, with a mandatory `reason` field). |

`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

| Route | Purpose |
| - | - |
| `/platform/commands` | Catalog index — browse, filter by risk class / source. |
| `/platform/commands/[commandId]` | Detail — args schema, risk class, network policy, examples, recent invocations. |
| `/platform/commands/audit` | Tier 3 audit and promotion candidates. High-frequency low-risk patterns surface here as candidates for Tier 1 promotion. |
| `/production/approvals` "Commands" tab | Held Tier 1 approvals (`hold` disposition). |
| Run-view command-class breakdown | "This run invoked 30 read-only, 12 mutates-fs, 3 network-egress, 1 exec." |

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](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-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?*

***

## Related

* [Tool sets](https://docs.gloo.com/forge/reference/tool-sets.md) — exhaustive table of every code tool set, its members, and who uses it.
* [Skills & Tools](https://docs.gloo.com/forge/build/define-an-agent.md) — how skills and tools compose into agent capabilities.
* [Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — the per-node factory-bound tool for file outputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.