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

Annotations already declare readOnlyHint=true, so the description is not burdened with safety disclosure. It adds useful behavioral context beyond annotations: the default status, what 'sent' and 'complete' mean semantically, and that the result provides uuids suitable for get_document. It doesn't mention pagination or return shape, but that's minor for a read-only list tool.

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 with no waste: purpose, status semantics plus default, and a usage example plus chaining instruction. Information is front-loaded and every sentence contributes to correct use.

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?

For a simple one-optional-parameter, read-only list tool with full schema coverage, the description covers the essential invocation details: default, filter semantics, and what the results enable (uuid → get_document). It omits explicit result shape and pagination, but the uuid mention implies the necessary output context, making it nearly complete.

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 covers the single parameter fully with a description and enum, so baseline is 3. The description adds value by mapping 'sent' and 'complete' to real-world meanings (waiting on signatures vs. fully signed), going beyond the raw enum labels.

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?

Description states a specific verb ('List'), a scoped resource ('this account's documents'), and the filtering dimension ('by status'). It differentiates from the sibling get_document by explicitly routing per-signer detail to that tool, and its use case ('what is still waiting to be signed?') makes the purpose unmistakable.

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?

Provides clear when-to-use guidance: which status values map to which real-world scenario, the default, and a concrete question the tool answers. It names get_document as the follow-up for per-signer detail, but does not explicitly exclude other siblings like list_templates, so it stops short of a 5.

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