Status: Stable.
Normative home:
toolCatalog.
Why this exists
A host's tool catalog lists the tools a caller may invoke, with a projection onto MCP ToolAnnotations. The shapes are schemas/v2/tool-descriptor.schema.json and schemas/v2/compact-tool-descriptor.schema.json.
The catalog
A host advertising toolCatalog MUST serve GET /tools (a ToolDescriptor[]) and GET /tools/{toolId}, both read-only.
- The list MUST hold only tools the caller may invoke in its tenant.
- An unknown or unauthorized
toolIdMUST return404. toolCatalog.sourcesnames the sources projected; a consumer MUST tolerate any subset.- A host SHOULD return tools sorted by
toolId, so an unchanged catalog reads identically.
The descriptor
toolIdMUST be unique in the catalog and stable for a host version.safetyTier: "exec"MUST carrysource: "host-extension".- A descriptor MUST NOT carry credential material.
- The host MUST assign
safetyTier,replayPolicyandegressitself, and MUST NOT copy them from an MCP server'sannotations, which are untrusted. - A
source: "mcp"tool the host has not classified MUST besafetyTier: "write".
annotations, when present, MUST carry all four MCP hints, derived from those fields and not from MCP defaults (upstream, destructiveHint and openWorldHint default to true):
| Hint | True iff |
|---|---|
readOnlyHint | safetyTier is pure or read |
destructiveHint | safetyTier is write or exec |
idempotentHint | replayPolicy is deterministic or idempotent |
openWorldHint | egress is not none |
Views and sessions
A host advertising toolCatalog.compactView MUST answer ?view=compact on both endpoints with CompactToolDescriptors (the list as { tools: [...] }) carrying the standard view's toolId set.
- A compact
inputSchemaMUST NOT use$ref,oneOf,allOf,anyOf,not,patternPropertiesordependentSchemasat any depth. - Any other
view, or a host not advertising it, yields the standard view.
A host advertising toolCatalog.sessionLifecycle MAY bracket calls with content-free tool.session.opened and tool.session.closed; a consumer MUST tolerate their absence.
Sources: RFCs 0078, 0112, 0204.