{"slug": "your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work", "title": "Your MCP Tool Definition Can Be 100% Spec-Compliant and Still Not Work", "summary": "A developer has launched a free, browser-based schema validator for Model Context Protocol (MCP) tool definitions, designed to catch both spec violations and practical compatibility issues that cause tools to fail in real clients. The tool checks hard requirements like missing 'name' or 'inputSchema' fields as errors, and flags client-dependent conventions such as name character restrictions and root-level 'type: object' assumptions as warnings. It runs entirely client-side and accepts single tools, arrays, or full tools/list responses.", "body_md": "I've been building a few free browser-based tools for people working with LLM APIs — a GPT token counter, a Citations API debugger, a Gemini thought-signature checker. This week I added one for the Model Context Protocol: a schema validator for MCP tool definitions.\n\nWhat sent me down this path was how small the actual MCP spec is. A `Tool`\n\nobject only has two required fields: `name`\n\nand `inputSchema`\n\n. That's it. No character restrictions on the name, no length cap, nothing that says `inputSchema`\n\nhas to describe an object at its root rather than, say, a string or an array. Read the raw JSON Schema for `Tool`\n\nand you'd reasonably conclude almost anything goes.\n\nThen you actually wire a server up to a real client and watch tools silently fail to load, or get called with arguments that don't match what you expected, and none of it was a JSON syntax error — the JSON was fine the whole time.\n\nThe gap is between what the spec *requires* and what every real client *assumes*. Tool names get used as function identifiers, so a name with a space or a slash in it works fine against the raw protocol and then gets rejected the moment it passes through an OpenAI-compatible bridge, because OpenAI's function-calling format does constrain names and the bridge inherits that constraint whether or not MCP itself does. `inputSchema`\n\nwithout `\"type\": \"object\"`\n\nat the root parses as valid JSON Schema and then breaks argument validation, because every SDK assumes tool arguments arrive as a JSON object of named parameters, spec text or not. A `required`\n\narray listing a property that doesn't exist in `properties`\n\nis a typo the spec has no opinion on, but it'll confuse the client's own JSON Schema validator in a way that's hard to trace back to that one line.\n\nNone of these are things a JSON validator catches, and none of them are exactly the MCP spec's problem either — they're the difference between \"technically valid\" and \"what actually works,\" which is exactly the gap a linter is for.\n\nSo the tool checks both: the hard spec requirements (missing `name`\n\n, missing `inputSchema`\n\n, a `required`\n\nentry that doesn't exist) as errors, and the practical client conventions (name character set, 64-character length caps, `$ref`\n\nsupport varying by client) as warnings, labeled clearly as which is which. Paste a single tool, an array, or a full `tools/list`\n\nresponse — it detects the shape and validates every tool in it. Free, runs entirely client-side, no server ever sees your tool definitions.\n\n[Try it here](https://bracketly.pages.dev/tools/mcp-tool-validator/) — feedback and edge cases welcome.", "url": "https://wpnews.pro/news/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work", "canonical_source": "https://dev.to/ethan_5b3022150e2c07a4030/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work-f8j", "published_at": "2026-08-01 07:15:58+00:00", "updated_at": "2026-08-01 07:52:21.139609+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-infrastructure"], "entities": ["Model Context Protocol", "OpenAI", "bracketly.pages.dev"], "alternates": {"html": "https://wpnews.pro/news/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work", "markdown": "https://wpnews.pro/news/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work.md", "text": "https://wpnews.pro/news/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work.txt", "jsonld": "https://wpnews.pro/news/your-mcp-tool-definition-can-be-100-spec-compliant-and-still-not-work.jsonld"}}