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

The annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so safety is already covered. The description adds only commercial terms: 'FREE during validation' and 'no key or credits needed'. It does not say what is compared, how breaking changes are classified, or what the output looks like. 'Existing source and input limits apply' is undefined boilerplate.

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

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

The text is short but front-loads pricing and validation disclaimers rather than the operative behavior. The sentences do not earn their place: they promote the tool's cost and constraints while omitting what it actually compares. The result is under-specified rather than concise.

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

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

An output schema exists, so return values need not be explained. But the tool takes nested objects, has a required parameter with no schema documentation, and performs a non-trivial semantic comparison. The description does not cover what 'breaking changes' means, how documents are supplied, or what the output contains. It is not complete enough for an agent to invoke it confidently.

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

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

Schema description coverage is 0%. The schema only declares an object with required 'before' and 'after' sub-objects and no field descriptions. The description does not explain what 'input' should contain, what the 'before'/'after' objects represent beyond being OpenAPI documents, or whether full documents or references are expected. With zero coverage, the description should have compensated, and it did not.

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

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

The description states a specific verb and resource: 'Detect selected direct breaking changes between OpenAPI 3.0 documents.' That is enough to distinguish it from siblings such as contracts_openapi_lint and data_json_diff. The qualifier 'selected direct' is vague, though, and leaves the scope of the comparison unclear.

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

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

The description gives no guidance on when to use this tool instead of alternatives, and it does not name any siblings or point to them. It only says to 'supply your task in input', which offers no selection logic. The agent must infer the right moment to call it from the title alone.

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