Compare MCP tool schemas without trusting the label

Find changed tool definitions in captured tools/list JSON, then separate a structural difference from a behavioral claim.

A tool can keep its name while changing its description or accepted parameters. Compare its full captured definition, then inspect the changed values privately. This workbench reports paths and change types rather than exposing descriptions or schema literals in a shared report.

Establish a comparable capture

Record the server identity, capture time, client context and authorization scope outside the imported JSON. Supply captures from the same server and equivalent access context. The MCP tools specification permits the advertised set to vary with authorization and to change over time. A missing tool therefore needs context before it becomes a removal conclusion.

If either capture has nextCursor, the report labels it incomplete. Obtain the remaining pages through your authorized capture workflow, merge them deliberately, and check for duplicate names. This tool neither contacts the server nor merges pages. An absent cursor does not prove your collector captured everything.

Worked example: search grows, delete appears

The before capture contains notes.search with one required query parameter. The proposed capture is:

{
  "tools": [
    {
      "name": "notes.search",
      "description": "Search project notes and archived notes.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "includeArchive": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "query"
        ],
        "additionalProperties": false
      },
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "notes.delete",
      "description": "Delete a note by ID.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ]
      },
      "annotations": {
        "destructiveHint": true
      }
    }
  ]
}

Select Captured tools/list and Load worked example in the workbench. The new includeArchive property produces changed paths beneath /tools/notes.search/inputSchema/properties. The description changes too. A new notes.delete definition appears as added fields.

Interpret the diff carefully

• Description change: inspect the complete new text privately. Determine whether its instructions or stated behavior affect approval. The workbench does not classify prompt injection.
• Parameter added: inspect its type, defaults and server handling. The presence of an archive option does not establish what data is reachable or which policy enforces access.
• Tool added: establish who can invoke it, under which scopes, and how a destructive action is confirmed. A name containing “delete” is not itself evidence that deletion occurs.
• Annotation supplied: treat read-only or destructive hints as claims, not enforcement. The specification tells clients not to trust annotations unless the server is trusted.

Structural change is not semantic change

The diff ignores object key order, but preserves array order. Reordering a schema's required array may create a visible diff without changing the accepted input set. A change from additionalProperties: false to true also appears as a changed path, with both values hidden. A reviewer must inspect the original schema to understand the consequence.

Tool-list order is ignored because tools are matched by name. A rename is an addition plus removal. Definitions are not fetched, dereferenced or validated against JSON Schema. Unknown tool properties remain in the diff; unknown result-envelope properties are noted but not compared.

Evidence still missing after comparison

A captured definition cannot prove that a server honors its schema, enforces authorization, handles cancellation, or limits filesystem and network access. Attach appropriate code review or authorized runtime evidence to the handoff. Keep the definition diff as one evidence item with a clear capture boundary.

Inspect the exact contract change

After comparison, filter the field path to inputSchema, description or annotations. Open the local value inspector and explicitly reveal the before and after values. The inspector is excluded from exports. This is a structural JSON diff: array order can change without changing JSON Schema meaning, and no schema references are resolved.