django-chainsaw-mcp

Overview Schema Source Related Servers Score Discussions Admin

api_contract

Read-onlyIdempotent

Describes the API contract of serializers, listing field names, types, read-only, required, nullable, and nested expansion details.

Instructions

The shape every serializer currently promises its clients.

Field names, types, whether each is read only, required, nullable, and what
the nested ones expand to. Resolved from the class definitions, so nothing
needs to run and no request needs to be sent.

Capture this on the branch you already shipped, commit the result, and
api_contract_check will tell a later branch what it broke.

Args:
    max_depth: how far to expand nested serializers.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`max_depth`	No

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

A4.1/5.0

Behavior4/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: the contract is resolved statically from class definitions, so no code execution or network request is needed. This explains the operational profile beyond what annotations alone convey.

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

Conciseness5/5

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

The description is compact and well-structured: the core purpose comes first, followed by the static-resolution behavior, then the workflow instruction, then the parameter explanation. Every sentence contributes useful information with no filler or repetition.

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?

Given the output schema exists and annotations cover safety, the description is sufficient for an agent to understand what the tool returns, why it exists, and how to use it in the branch workflow. The only minor gap is that it does not explicitly say where or how the contract result is emitted, but the output schema partially covers that.

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

Parameters4/5

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

Even though schema description coverage is 0%, the description provides an Args section explaining that max_depth controls how far nested serializers expand, which adds semantic meaning beyond the schema's plain integer type and default value. It could be more precise about valid ranges or edge cases, but for a single optional parameter it is adequate.

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 identifies the tool as capturing the current API contract shape that serializers promise, including field names, types, nullability, and nested expansion. It uses specific language ('Capture this', 'Resolved from the class definitions') that distinguishes it from similarly named siblings like api_contract_check, which is described as the later comparison step.

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

Usage Guidelines4/5

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

The description gives explicit workflow context: run this on the already-shipped branch, commit the result, and then api_contract_check will report what a later branch broke. This clearly implies when to use it and how it relates to the closest sibling, though it does not enumerate exclusions or alternative tools.

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