api-contract-qa

Assess impact on consumers

assess_impact

Determine which known API consumers a spec change breaks and why, including field-level impact when consumer fields are listed, and return a breaking or compatible verdict.

Instructions

Which known consumers a spec change breaks, and why (field-level when consumers list the fields they read/send). Verdict: breaking | breaking_no_known_consumers | compatible; needs_human when 2+ consumers or a high-criticality consumer break. Consumers come from .qa-mcp/consumers.yaml.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "base_spec": "<base_spec>",
      "head_spec": "<head_spec>"
    },
    "name": "assess_impact"
  }
}

Input Schema

Name	Required	Description	Default
`base_spec`	Yes
`head_spec`	Yes
`write_report`	No
`consumers_file`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 13, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations supplied, the description carries the full burden and does well: it discloses the complete verdict enum, the escalation rule (needs_human when 2+ consumers or a high-criticality consumer break), and the conditional field-level detail when consumers declare fields read/sent. The notable gap is the write_report side effect — nothing says what gets written or where, which matters for a non-read-only flag.

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

Conciseness4/5

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

Three sentences, no filler, and the core purpose is front-loaded ahead of the verdict and escalation details. The nested parenthetical for field-level reporting makes one sentence slightly dense, but every clause adds information.

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

Completeness3/5

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

The verdict and escalation semantics are well covered for a tool with no annotations and no output schema. What is missing is the effect of write_report and any indication of the report's shape or size when consumers are many, leaving the agent unable to predict side effects or output volume.

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

Parameters3/5

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

Schema description coverage is 0%, so titles like 'Base Spec' and 'Consumers File' carry no meaning on their own; the description compensates by explaining the comparison (base vs head) and by naming .qa-mcp/consumers.yaml as the default consumers source. However, write_report receives no explanation at all and consumers_file's override semantics are only loosely implied.

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

Purpose5/5

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

States a specific verb and resource: identifies which known consumers a spec change breaks, and why. It also enumerates the exact verdict vocabulary (breaking | breaking_no_known_consumers | compatible), which separates it from plain diffing tools like diff_contracts and from consumer-discovery tools like discover_consumer_usage without needing to name them.

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?

Usage is implied rather than stated: the base_spec/head_spec pair plus 'spec change' signals this is the post-diff consumer-impact step, and the consumers source (.qa-mcp/consumers.yaml) implicitly says it does not discover consumers itself. There is no explicit 'use X instead when Y' routing, so an agent must infer its place in the workflow.

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

Deploy Server