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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. The description adds useful behavioral context by specifying what kind of analysis is performed and what result categories the agent can expect, though it does not address version-omission behavior.

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?

Two focused sentences: the first establishes the core operation and outputs, the second gives a direct routing instruction. No filler or redundant restatement of the tool name.

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?

The description is largely complete for an agent selecting and invoking this tool, especially with the output schema present and a sibling alternative named. The main gap is the implicit assumption that two versions are compared while only service is required, leaving the default comparison behavior under-specified.

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?

The input schema already documents all three parameters with descriptions, including examples for service and the roles of fromVersion/toVersion, so baseline is 3. The description adds little parameter-level meaning beyond the phrase 'Compare two versions', and it does not clarify behavior when the optional versions are omitted.

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 identifies a specific verb-resource pair: comparing two versions of a third-party API and returning breaking changes. It lists concrete outputs (removed endpoints, parameter type changes, removed request body fields, migration guides), and the closing sentence distinguishes it from factreason_package_upgrade_advisory.

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 explicitly states when NOT to use this tool: for npm or PyPI packages, use factreason_package_upgrade_advisory instead. This gives the agent a clear decision rule and differentiates the tool from a key sibling.

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