Concept card

MCP Tool Specification Standard — JSON Schema + Annotations

As of 2026-10-06

Edited by Cédric Mary, sole editor and publication director — 27 years in the SAP ecosystem. How these pages are produced, and where automation is used.

What is MCP Tool Specification Standard?

Most production MCP tool failures aren't handler bugs — they're under-specified descriptions and loose input schemas that mislead the model into wrong tool selection or invalid arguments.

An MCP tool is fully described by four artefacts: a name, a description, a JSON Schema input specification, and an optional annotations block. The quality of those four artefacts determines whether an LLM client picks the right tool, calls it with valid arguments, and interprets the result correctly. Most production failures in MCP servers are not handler bugs; they are under-specified descriptions and loose input schemas that mislead the model into the wrong tool selection or invalid argument generation.

What Each Artefact Carries

The name is a stable identifier, conventionally written as short lower-case words strung together, describing an action and a noun, such as a tool that searches a firm directory or one that retrieves a single firm's full profile. Stability matters more than elegance here: renaming a tool between server versions silently breaks every agent prompt, cached plan, or fine-tuned routing behaviour that referenced the old name. The description is the artefact the model actually reads to decide whether a tool fits the user's intent, and it is the single highest-leverage piece of text in the whole server. A bare "Search firms" gets mis-selected the moment a second search-shaped tool exists in the same context, while a fuller description naming what directory is being searched, how many results come back, which fields the caller can filter on, and which companion tool to call next for a full record gives the model enough to route correctly and to plan the following step.

Why it matters

A vague description like "Search firms" gets mis-selected in a multi-tool context; naming the action, inputs, output shape and follow-up tool resolves the ambiguity.
A loosely typed property like {type: string, description: country} produces random ISO codes or full country names depending on the model; constraining it with an explicit enum fixes the ambiguity at the schema level.
The Zod-first pattern (one schema definition emitting both the runtime validator and the JSON Schema) eliminates schema drift between what the handler enforces and what the LLM sees.

Key points

Four artefacts per tool — name (snake_case stable id), description (action+noun lead), input spec (JSON Schema 2020-12), annotations (planning hints).
Description quality drives tool selection — lead with action, list inputs and output shape, call out constraints; vague descriptions mis-route the LLM.
Input spec — JSON Schema 2020-12 with required, properties (type+description+enum/pattern), additionalProperties:false to reject typos.
Zod-first pattern — define schema once in TypeScript, emit both runtime validator and JSON Schema for the LLM.
Annotations (spec rev 2025-06-18) — title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint; planning hints, not runtime enforcement.
The MCP specification's move to revision 2026-07-28 (elicitation, extensions framework) left this card's four-artefact model and annotations block unchanged — annotations remain exactly the 2025-06-18 readOnlyHint/destructiveHint/idempotentHint/openWorldHint set.
For an SAP-facing tool — a write action against Datasphere or S/4HANA — a missing or wrong destructiveHint is a governance failure, not a UX nicety: it decides whether an MCP-aware agent runtime shows a human a confirmation step before an irreversible SAP transaction executes.

Terms used on this page

JSON Schema 2020-12: The IETF-draft schema dialect MCP tool input specs use; types, required, properties, enum, pattern, additionalProperties — the LLM reads it to know how to construct a valid call.
Tool annotations: Optional hints carried alongside name/description/inputSchema since the 2025-06-18 spec revision: title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint — the model uses them for planning, the server does not enforce them at runtime.
Zod-first schema pattern: Define an input schema once in TypeScript using Zod, then emit both the runtime validator and the JSON Schema string the LLM sees — single source of truth, no drift between what the spec advertises and what the handler accepts.
Tool mis-routing: The failure mode where the LLM picks the wrong tool for a user intent because the descriptions of two tools overlap or are too vague; the #1 production bug class in MCP servers, fixed by surgical descriptions and clear annotations.
destructiveHint: The annotation flagging that a tool call may cause an irreversible or hard-to-undo change. For SAP write actions with no trivial undo — a posted journal entry, a released purchase order — err toward setting this true even when the tool's description reads as routine.
readOnlyHint: The annotation marking a tool as safe to call without user confirmation because it only reads data, with no side effect. The correct default for lookup-shaped SAP tools such as querying a Datasphere model or reading a master-data record.

Sources

Full card available to members. What the full card adds: the full decision framework · the SAP vs Snowflake / Databricks / Fabric comparison · the common pitfalls and their fix · the cheat sheet · the architecture schemas · the code blocks · the facts worth quoting.

Open in the app →