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

Annotations already carry readOnly, idempotent, non-destructive and closed-world hints, so safety basics are covered. The description nonetheless adds real value by bounding expectations: it 'does not prove all terms match', does not 'authorize a financial action' and does not 'replace household approval', plus it enumerates the categories of information returned (checked-field changes, source versions, affected recorded work, preserved history).

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?

Three sentences, front-loaded with the core comparison action, followed by the return contents and then the limitations. The middle sentence is a long enumerated list, but with no output schema it earns its space; nothing is redundant.

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?

With no output schema, the description must convey what comes back, and it does so by naming the five categories of read results (changes, versions, affected work, history, next step). It also closes the expectation gaps around proof of term matching and financial authorization. A reader still lacks clarity on how this differs from the sibling capital-call state tools.

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% and both parameter descriptions are already detailed (including the note that the current ID may equal the recorded ID on reprocessing). The description only reinforces that both documents must be identified explicitly and reiterates that no write authority is granted, adding little beyond the schema. Baseline 3 is appropriate.

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?

Names a specific verb (compare) and a specific resource (two explicitly identified capital-call documents) against the recorded job, which an agent can distinguish from generic document search siblings. It does not, however, explicitly differentiate itself from the closely named siblings get_capital_call_job_state and get_capital_call_source_state, which a reader would naturally conflate.

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 phrase 'two explicitly identified' implies the caller must pick both documents deliberately, and the final sentence gestures at a 'next permitted review step', which hints at workflow context. But there is no explicit statement of when to reach for this over get_capital_call_job_state or get_capital_call_source_state, and no stated prerequisites beyond identification.

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