django-chainsaw-mcp

Overview Schema Source Related Servers Score Discussions Admin

api_contract_check

Idempotent

Compare the current API response shape against a committed snapshot to identify breaking, risky, or additive changes. Use update to overwrite the snapshot when changes are intended.

Instructions

What this branch changes about the API, and who it breaks.

Removing a serializer field is a one line diff that reads as tidying up.
The client on a version nobody updated still reads that field. Every tool
that catches this needs the app running: drf-api-checker records real
responses during a test run, OpenAPI diffing needs the schema generated.

Changes come back sorted by who they hurt. Breaking means an existing
client stops working: a field it reads disappears, a field it omits becomes
required, a type or a constraint narrows. Risky means it still parses but
the values may surprise it. Additive means nobody notices.

Args:
    snapshot_path: the committed contract to compare against.
    update: overwrite the snapshot with the current shape instead of
        comparing. Do this once you have decided a change is intended.
    max_depth: how far to expand nested serializers.

Input Schema

TableJSON Schema

Name	Required	Default
`update`	No
`max_depth`	No
`snapshot_path`	No	.django-chainsaw-contract.json

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.3Sep 9, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate idempotent and non-read-only behavior, but the description adds useful operational context: 'update' overwrites the snapshot, 'max_depth' controls expansion, and results are sorted by impact. It defines breaking, risky, and additive outcomes clearly. No contradiction with annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a purpose statement and an Args section, but it includes somewhat narrative passages like the serializer field removal example and the drf-api-checker/OpenAPI aside. These add color but are not strictly necessary for selecting or invoking the tool, making it less concise than it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and all three parameters documented, the description is largely complete. It explains the comparison semantics, the update mode, and the depth control. The only small gaps are the exact format expected for snapshot_path and any prerequisites for the current API shape to be available, but these are not severe.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the Args section fully compensates by explaining all three parameters: snapshot_path is the committed contract to compare against, update switches to overwrite mode with a clear caution, and max_depth controls serializer expansion depth. This adds exactly the meaning the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly communicates that the tool compares API contract snapshots and classifies changes as breaking, risky, or additive. It uses concrete verbs like 'compare' and 'overwrite' in the Args section and describes the resource. However, it does not explicitly differentiate itself from the sibling tool 'api_contract', so an agent may have to infer which one to call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for reviewing contract changes when a branch modifies the API, and it gives explicit guidance that 'update' should only be used once a change is intended. However, it does not directly state when to choose this tool over alternatives like 'api_contract', and the reference to drf-api-checker and OpenAPI diffing is more about other approaches than actual selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.