darinor
Tools

MCP Tool Schema Linter

Check a Model Context Protocol Tool definition — or a whole server's tools/list response — against the spec right in your browser. Nothing is uploaded.

Paste a single Tool object, a bare array of tools, or a tools/list response ({ "tools": [...] }) to lint every tool at once.

Findings1 error
Structure
  • info /title

    No "title" or "annotations.title" set — clients fall back to "name" for display (precedence: title, annotations.title, name). A human-facing title improves UX.

  • warning /description

    Description is very short (<10 chars) — likely not enough for a model to disambiguate this tool from others.

Annotations
  • warning /annotations/destructiveHint

    Meaningless combination — "destructiveHint" only applies when "readOnlyHint" is false.

Schema safety
  • error /inputSchema/properties/reason/$ref

    External $ref URIs must not be auto-dereferenced per spec, and a schema that cannot resolve one SHOULD be rejected; this schema references an external URI: https://example.com/schemas/reason.json

Worked example: a mismatched read-only hint

Paste this definition into the linter. It declares a read-only operation and a destructive hint at the same time; the linter reports a warning at /annotations/destructiveHint. The description also needs more detail.

{
  "name": "delete_file",
  "title": "Delete a file",
  "description": "Delete",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string"
      }
    },
    "required": [
      "path"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": true
  }
}

For a tool that actually deletes files, describe its allowed scope and set readOnlyHint to false. Hints describe behavior; they do not enforce permissions. Verify authorization and path restrictions in the server, then test the call boundary using the agent tool-call validation guide. The MCP tools specification treats annotations from untrusted servers as untrusted too.

About this tool

MCP Tool Schema Linter

This linter checks MCP Tool objects against the Model Context Protocol spec — not generic JSON validity, but the constraints specific to tool definitions: required fields, tool-name rules, the inputSchema root-type rule, icons, annotation hint semantics, x-mcp-header annotations, and safe use of $ref in schemas. Paste one Tool object, or a whole tools/list response, and every tool gets its own findings.

It's built against the 2026-07-28 spec revision, which permits $ref, $defs, and composition keywords (allOf/anyOf/oneOf/not, if/then/else) inside tool schemas and lets outputSchema be any JSON Schema, not only an object. That surface area is new, so this tool flags the failure modes it introduces: external or unresolved $ref pointers, unbounded nesting, and oversized schemas. It also validates the x-mcp-header extension that mirrors a parameter into an HTTP header, where a single violation makes clients drop the whole tool.

Findings are grouped into Structure, Icons, Annotations, Schema safety, and x-mcp-header, each with a severity — error for spec violations, warning for likely bugs, info for completeness notes. Everything runs in your browser; the tool definition you paste is never uploaded.

When to use it

  • Review a tool before publishing an MCP server

    Paste each Tool definition to catch a missing inputSchema type or a description too thin for a model to act on, before clients see it.

  • Audit annotations before shipping destructive tools

    Confirm readOnlyHint, destructiveHint, and idempotentHint are set consistently — a mis-set default can make a safe tool look destructive to a client that gates on hints.

  • Check a schema after adding $ref/$defs

    The 2026-07-28 spec allows composition keywords in tool schemas; this catches external or unresolved $ref pointers and excessive nesting before they reach a client.

  • Audit a whole server's tool roster at once

    Paste the server's tools/list response directly and get a per-tool breakdown, so a bad tool doesn't hide among the good ones.

Questions

Is my tool definition uploaded anywhere?

No. Linting runs entirely in your browser via JavaScript. Nothing is sent to a server.

Which MCP spec revision does this check against?

The 2026-07-28 revision: the Tool schema, the tools page, the JSON Schema usage rules, and the Streamable HTTP x-mcp-header rules. Tools written for 2025-11-25 mostly lint the same; the differences are $ref/$defs/composition support in schemas, non-object outputSchema, and x-mcp-header.

Why does inputSchema need type: "object" at the root?

MCP constrains tool input schemas to an object root, unlike generic JSON Schema which allows any root type. A tool whose inputSchema root isn't an object is spec-non-compliant.

Can outputSchema be an array or a string?

Yes. In the 2026-07-28 spec an outputSchema can be any valid JSON Schema 2020-12 because structuredContent can be any JSON value. Only inputSchema is restricted to an object root, since tool arguments are always an object. Older versions of this linter wrongly required an object outputSchema.

What is x-mcp-header and why does the linter check it?

It is an extension keyword on an inputSchema property that tells Streamable HTTP clients to mirror the argument into an Mcp-Param-{name} header so gateways can route on it. The rules are strict: a valid header token, unique ignoring case, a string, integer, or boolean type (not number), and reachable only through properties keys, never items, anyOf, or $ref. A client that finds one violation must drop the entire tool from tools/list, so the tool silently disappears. Don't mirror secrets, since headers are visible to proxies and logs.

Why flag a tool with no annotations at all?

MCP clients apply defaults when annotations are absent: readOnlyHint=false, destructiveHint=true. A genuinely read-only tool with no annotations will be treated as destructive by clients that respect hints, which can trigger unnecessary confirmation prompts.

Does this validate arguments passed to the tool, or the tool definition itself?

The definition itself — the Tool object a server declares. To validate arguments against a tool's inputSchema, use the JSON Schema Validator.

Can I lint my whole server's tool list at once?

Yes. Paste a bare array of Tool objects, or a full tools/list response ({ "tools": [...] }), and each tool is linted individually with its own findings and status.