MCP Schema Validator

Model Context Protocol (MCP) lets AI assistants like Claude, GPT, and Gemini call external tools through a standardised interface. Each tool declares a JSON Schema that tells the model what arguments it accepts — and if that schema is wrong, incomplete, or confusing, the model picks the wrong tools, sends bad arguments, or wastes tokens on retry loops.

This validator checks your MCP tool definitions against the MCP specification (revision 2025-11-25) and flags issues that affect how LLMs interpret and use your tools. It catches spec violations (missing required fields, malformed schemas) and LLM-friendliness problems (vague descriptions, missing type annotations) that the spec doesn't require but that directly impact tool selection quality.

Two categories of findings, clearly labelled: • Errors — spec requirements your definition fails to meet. These may break clients that enforce the spec strictly. • Warnings — things the spec allows but that cause real problems in practice: models can't infer what a parameter does if it has no description, and token budgets blow up when schemas are bloated.

Everything runs in your browser. No tool definitions are sent to a server — the validation is pure JSON Schema checking plus heuristic analysis, with no network calls.

The validator implements the MCP tool definition requirements from the official specification (revision 2025-11-25, confirmed 2026-06-23). It performs two layers of analysis:

**Layer 1: Spec Compliance** Checks that map directly to MUST/SHOULD requirements in the MCP specification: • Tool must have a `name` (non-empty string, 1-128 chars of [A-Za-z0-9_-]) • Tool must have an `inputSchema` (non-null JSON Schema object) • `inputSchema.type` must be "object" • `inputSchema.properties` and `required` must be well-formed • No duplicate tool names in a single server • `required` array must not reference properties not in `properties`

**Layer 2: LLM-Friendliness Heuristics** Recommendations based on how LLMs actually use tool definitions: • Description presence and length (LLMs use descriptions for tool selection) • Property-level descriptions (models need to understand each argument) • Type annotations on properties (untyped properties cause model guessing) • Schema complexity vs. token cost (simpler schemas = cheaper tool loading)

Token cost estimation uses a ~4 chars per token approximation for the JSON context that would be sent to an LLM. The actual token count varies by tokenizer (cl100k_base for GPT models, Claude's tokenizer for Anthropic models), but the approximation is close enough for budget planning.