compare_versions

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

With no annotations provided, the description carries the full behavioral burden. It discloses the core operation (showing a diff), the minimum date constraint ('Both dates must be 2017-01-03 or later'), and the intent of comparing pre/post amendment text. It does not explicitly state that the tool is read-only, but 'Show' and 'diff' strongly imply a non-destructive operation. Some detail about output formatting is left to the output schema, which is reasonable.

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 description is four tight sentences: purpose, workflow, parameter mapping, and a constraint. Each sentence earns its place, the most important information is front-loaded, and there is no repetition of schema details.

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 complete for an agent to call the tool correctly: it explains what the tool does, how to choose dates, which sibling to use first, and an important date restriction. With an output schema present, the description does not need to document return values. The optional max_chars parameter is absent, but its name and default make it self-evident, so this is not a blocking gap.

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 description adds meaningful semantic guidance beyond the schema: it maps date_a to the day before an amendment and date_b to the amendment date, and imposes a global minimum date. The schema already covers citation and date formats, and date_b's optionality. However, max_chars is not mentioned in the description and appears to lack schema coverage, so the description does not fully compensate for that one parameter.

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 opens with a clear verb-and-resource statement: 'Show how a citation's text differs between two dates, as a diff.' This immediately distinguishes it from siblings like lookup_citation and what_changed. The mention of what_changed further clarifies that compare_versions is specifically for diffing text between dates, not for finding dates.

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 says 'Use what_changed first to find amendment dates worth comparing' and then gives a concrete recipe for date_a and date_b. This tells the agent when to use this tool and how it fits with an alternative, leaving no ambiguity about the recommended workflow.

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