Get a rule's version history

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the returned shape (effective dates, values, citation) and the status taxonomy current/superseded/withdrawn, plus the informational-not-legal-advice caveat. It says nothing about result size or pagination for a history that is potentially unbounded.

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?

Front-loaded with the scope and output facets, followed by the example, the exclusion, and the cross-reference to resolve_version. Dense but every sentence carries information; the trailing 'Informational only, not legal advice' is the only line that is closer to boilerplate than instruction.

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?

There is no output schema, and the description compensates by enumerating return fields and status values, which is exactly what an agent needs to interpret results. Combined with annotations covering safety and the schema covering all three parameters, nothing essential to correct invocation is missing beyond pagination behavior for large histories.

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 coverage is 100% with per-parameter descriptions for domain, rule_type and jurisdiction, so the schema carries the semantics. The description's only added meaning is a concrete paired example (`minimum_wage` + `us-wa`) showing how the two required slugs combine. That is marginal on top of an already complete schema, so baseline 3 applies.

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?

States a specific verb+resource+scope: 'List every version ever published of one jurisdiction's rule', and enumerates the returned facets (effective dates, values, citation, status). The scope clause 'Covers that jurisdiction's own rule only; other levels that apply (e.g. us) are separate calls' lets an agent distinguish this from get_rule / get_rule_as_of / list_changes without opening any schema.

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?

Gives clear context for when this is the right call (full version history for a single jurisdiction) and explicitly scopes out other jurisdiction levels as separate calls. It also routes forward by noting each entry's `id` can be passed to resolve_version. It stops short of naming get_rule or get_rule_as_of as the alternatives for current or point-in-time lookups.

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