ADR 0024: Tool definitions for agents: MCP and function calling from one source¶
Status: Accepted ยท 2026-11-17 (decided by the maintainer in #46)
Context¶
An agent needs more than the list of commands: how to call each one, which parameters, which values each enum accepts and what they mean, and whether the call changes anything. Tool schemas are read by many clients and model providers, and some accept only a subset of JSON Schema.
Decision¶
Tool definitions are generated from the command schemas, never written by hand. Every definition: is inlined without $ref; uses one type per type keyword, with an optional value written as anyOf of the type and null; carries the meaning of every enum value in the field description; carries a minimal and, where useful, a maximal input example taken from golden cases; states units and formats in descriptions; carries annotations readOnlyHint, destructiveHint and idempotentHint, and _meta with the command version and status. A compact profile removes only annotations, never a validation keyword. A portable variant serves providers with limited JSON Schema support. Errors are returned with isError and the whole error report as structured content. CI drives the MCP server with the MCP Inspector in strict mode and fails on a single warning.
Consequences¶
Every agent and every provider sees the same contract and can correct a call in one round. Each provider format becomes a contract to test.