Concept card

MCP Tool Specification Standard — JSON Schema + Annotations

As of 2026-07-24T14:00:00Z

Edited by Cédric-Olivier Mâry, 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 — JSON Schema + Annotations?

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.

How The Input Schema Carries The Real Weight

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.
MCP Tool Specification Standard — JSON Schema + Annotations is mastered only when it changes a named buyer decision.
Start with the semantic contract and control model before demonstrating the tool.
Use current SAP, analyst, study, KG, and news signals as evidence, not decoration.
Separate verified facts from directional trends and modeled assumptions.
Define owner, metric, threshold, support path, and rollback before scaling.

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.
Decision owner: The accountable person who accepts the trade-off and funds the next action.
Semantic contract: The shared definition of business terms, metrics, entities, and access rules used by tools and teams.
Control plane: The layer that applies policy, access, lineage, monitoring, and escalation across the operating model.
Evidence grade: A label that separates verified fact, directional signal, modeled assumption, and field observation.

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 →