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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces 'Changes nothing.' Beyond that it discloses return-behavior details the annotations don't: the audit trail contents (each open, signature, payment with time), that client creation/linking happens on payment, and the Stripe-connected indicator.

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-loads the core behavior (status listing) before the agreement_id branch, then the downstream routing. Dense but mostly earns its place; the Stripe note and next-step routing are slightly incidental but relevant to agent planning.

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?

No output schema, so the description must convey return contents—it does (statuses, links, per-event audit trail, Stripe connection). For a single-param read tool this leaves nothing an agent needs to call it correctly unstated.

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 single agreement_id parameter has 0% schema description coverage, but the description fully compensates by explaining its branch semantics: omit it to list all agreements, supply it to get one agreement plus its audit trail. That is the key meaning an agent needs.

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 resource (agency agreements) and precisely what is returned: status lifecycle (drafted, sent, opened, signed, paid/withdrawn) with links. This clearly distinguishes it from siblings like agreement_send, agreement_void, and agreement_draft, which mutate rather than report state.

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?

Explicitly describes the two modes: without agreement_id it lists all agreements' standing; with agreement_id it returns one agreement plus audit trail. It also routes the agent forward once paid (client_access_link, then autopilot_setup_questions). No explicit 'when not to use' or named competing read tool, which keeps it just under a 5.

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