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.
Operations
GET /api/v3/tools— listToolsGET /api/v3/tools/{toolId}— getToolGET /api/v3/tool-sets— listToolSetsGET /api/v3/tools/{toolId}/versions— listToolVersionsGET /api/v3/tools/{toolId}/agents— listToolAgentsGET /api/v3/tools/{toolId}/executions— listToolExecutionsGET /api/v3/tools/{toolId}/usage— getToolUsageGET /api/v3/most-used-tools— listMostUsedToolsGET /api/v3/tools-needing-attention— listToolsNeedingAttentionGET /api/v3/tools/{toolId}/audit-histories— listToolAuditHistoryGET /api/v3/tools/{toolId}/sandbox-rejections— getToolSandboxRejections
tools:manage at the platform scope; reached from MCP through forge_call_operation):
POST /api/v3/tool-sets— createToolSetPATCH /api/v3/tool-sets/{setId}— updateToolSetDELETE /api/v3/tool-sets/{setId}— deleteToolSet — also revokes every agent grant of the set
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 asid (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.
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.
