Skip to content

MP005: valid-json-schema

The inputSchema must validate as JSON Schema 2020-12 and its root type must be "object".

At a glance
Category schema
Default severity error
Auto-fixable no
LLM-gated no
Stable since v0.1.0

What this rule checks

mcpolish runs jsonschema.Draft202012Validator.check_schema() on each tool's inputSchema. If the schema itself is malformed (not the data it validates, the schema), MP005 fires.

It also fires if the root type is anything other than "object". MCP requires an object at the root because tool arguments are always a dict.

Why it matters

A broken inputSchema breaks the tool. The MCP host validates incoming arguments against the schema before dispatching to your code. A bad schema either accepts garbage or rejects valid input. Either case is bad for the agent.

Example: code that triggers this rule

from mcp import Tool

TOOL = Tool(
    name="bad_schema",
    description="Use this when the user wants the thing. Returns the thing.",
    inputSchema={"type": "string"},   # root must be "object"
)

MP005 fires with a clear message: inputSchema.type must be 'object'.

Another trigger: typo in a keyword.

inputSchema={
    "type": "object",
    "proprties": {  # typo
        "x": {"type": "integer"},
    },
}

The jsonschema validator catches the unrecognised keyword name. Whether it counts as an error depends on the keyword; mcpolish surfaces the validator's complaint.

Example: how to fix it

inputSchema={
    "type": "object",
    "properties": {
        "x": {"type": "integer"},
    },
    "required": ["x"],
}

Object root, correct keyword spellings.

Configuration

MP005 has no knobs. To skip it:

[tool.mcpolish]
ignore = ["MP005"]

When to disable this rule

Never. A broken schema is a runtime bug. If MP005 fires, fix the schema.

How the check works under the hood

For each tool, mcpolish calls Draft202012Validator.check_schema(schema). The validator raises SchemaError on malformed input; mcpolish catches that and emits the error message verbatim. If the schema validates but the root type is not "object", mcpolish emits its own error.

The check happens once per tool. The validator does not run on every incoming request; that is what your MCP host does at runtime.

  • MP004 require-required-array: schemas that validate but miss the required array.
  • MP030 param-type-mismatch: schema is valid but disagrees with description.

References