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

> Read safe metadata from the platform-global tool catalog.

The Tools domain exposes a platform-global, read-only catalog under the `tools:read` scope. It has no invocation endpoint.

`ToolSummary` includes identity, category, effect flags and version identity. `ToolDetail` adds optional stored input and output JSON Schemas, safe effect metadata, required permission names and an optional vendor key. A legacy tool with no stored schema omits that field. Stored schemas pass through unchanged.

The catalog never returns credential configuration, connection names and hosts, internal function paths, sandbox commands, egress allowlists, owners, creators or quality findings. Which agents hold a tool is a separate read: [`listAgents`](#tool-insights).

## Operations

* `GET /api/v3/tools` — [listTools](https://docs.gloo.com/forge/reference/http-api/tools/list.md)
* `GET /api/v3/tools/{toolId}` — [getTool](https://docs.gloo.com/forge/reference/http-api/tools/get.md)
* `GET /api/v3/tool-sets` — [listToolSets](https://docs.gloo.com/forge/reference/http-api/tools/listSets.md)
* `GET /api/v3/tools/{toolId}/versions` — [listToolVersions](https://docs.gloo.com/forge/reference/http-api/tools/listVersions.md)
* `GET /api/v3/tools/{toolId}/agents` — [listToolAgents](https://docs.gloo.com/forge/reference/http-api/tools/listAgents.md)
* `GET /api/v3/tools/{toolId}/executions` — [listToolExecutions](https://docs.gloo.com/forge/reference/http-api/tools/listExecutions.md)
* `GET /api/v3/tools/{toolId}/usage` — [getToolUsage](https://docs.gloo.com/forge/reference/http-api/tools/getUsage.md)
* `GET /api/v3/most-used-tools` — [listMostUsedTools](https://docs.gloo.com/forge/reference/http-api/tools/listMostUsed.md)
* `GET /api/v3/tools-needing-attention` — [listToolsNeedingAttention](https://docs.gloo.com/forge/reference/http-api/tools/listNeedingAttention.md)
* `GET /api/v3/tools/{toolId}/audit-histories` — [listToolAuditHistory](https://docs.gloo.com/forge/reference/http-api/tools/listAuditHistory.md)
* `GET /api/v3/tools/{toolId}/sandbox-rejections` — [getToolSandboxRejections](https://docs.gloo.com/forge/reference/http-api/tools/getSandboxRejections.md)

Workspace tool sets (`tools:manage` at the platform scope; reached from MCP through `forge_call_operation`):

* `POST /api/v3/tool-sets` — [createToolSet](https://docs.gloo.com/forge/reference/http-api/tools/createSet.md)
* `PATCH /api/v3/tool-sets/{setId}` — [updateToolSet](https://docs.gloo.com/forge/reference/http-api/tools/updateSet.md)
* `DELETE /api/v3/tool-sets/{setId}` — [deleteToolSet](https://docs.gloo.com/forge/reference/http-api/tools/deleteSet.md) — also revokes every agent grant of the set

Catalog pages use a stable keyset cursor and a maximum limit of 50. `meta.partial: true` means the catalog reader reached its 5,000-row safety cap.

`listToolVersions` returns an active or deprecated tool's immutable versions, newest first: each `PrimitiveVersion` carries the version's id, exact version, status, synthesis tier, creation time, and whether the tool's active or canary head points at it. A version's configuration is never returned. A page at a time (`limit` 1–100, default 100): continue while `meta.hasMore` is `true`, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may be short while more remain, and the list never answers `meta.partial`. Retiring or reinstating a tool version stays in the Console.

## Tool insights

Seven reads show a tool the way the Console's tool detail page and tool catalog do. Each takes the tool's id or slug as `id` (the two catalog-wide lists take none). A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or out-of-range parameter is `400 bad_request`.

| Read | You need | Returns |
| - | - | - |
| `listAgents` | `agents:read`, each agent decided at its home | The agents the tool is assigned to (`status=active`) or was revoked from (`status=revoked`), and whether each assignment grants or denies it. An agent you cannot read, or another person's Personal Agent, is counted in `meta.hiddenCount` for the page that left it out, never listed. A page at a time, `limit` 1–500 (default 500). |
| `listExecutions` | `agents:read` at the platform scope | The newest calls: status, timing, cost, tokens and governance disposition. The agent appears only when you can read it, the run only when you can read the run, and the summaries and error (up to 500 characters, secrets masked) only under a readable parent run; otherwise `contentWithheld` is true. Never the raw input or output. A page at a time, `limit` 1–100 (default 50). |
| `getUsage` | `agents:read` and `tools:read` at the platform scope | Calls, failures, cost and tokens since `sinceMs`, and the top callers among the agents you can read; the rest are counted in `hiddenCallerCount`. |
| `listMostUsed` | `tools:read` at the platform scope | The tools called most in the last seven days, of any status, as the Console counts them. |
| `listNeedingAttention` | `tools:read` at the platform scope | Tools of any status whose input schema is invalid or that are disabled, and why. |
| `listAuditHistory` | `agents:read` at the platform scope | The tool's history, newest first: the event, its category, the kind of actor and when; never who acted or the detail. Page with `meta.nextCursor`. |
| `getSandboxRejections` | `agents:read` at the platform scope | How many of the tool's sandbox commands were rejected since `sinceMs`: a count, never a command. |

`sinceMs` is an epoch time in milliseconds within the last 90 days; it defaults to seven days ago. `listAgents` and `listExecutions` page at the database: continue while `meta.hasMore` is `true`, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may be short while more remain, and the list never answers `meta.partial`. `meta.partial` is true when another read reached its read budget and may be incomplete; `listMostUsed` is a bounded top-N list and does not answer it.


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