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

Annotations only supply openWorldHint=false and destructiveHint=false; the description adds the PDF-retention guarantee, the FAILED_PRECONDITION refusal conditions, the envelope-void prerequisite, and the document-hub read path. These are meaningful behavioral constraints well beyond what the annotations convey, and nothing contradicts them.

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?

Single front-loaded paragraph leading with the core action before branching into edge cases. Dense but largely earned; the error-handling clauses are verbose yet operationally relevant, with minimal wasted wording.

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?

An output schema exists, so return values need no explanation. Given the mutation semantics, refusal conditions, prerequisite sequencing, and retry guidance are all covered, nothing an agent needs to call this correctly is missing.

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 50% and the enum already enumerates all status values, so the schema carries the parameter detail. The description adds semantic intent for a couple of states ('completed once signing finishes', 'void to retire an unsent draft') but does not explain the id wrapper or map the remaining statuses, so it only marginally exceeds baseline.

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 and resource ('Moves a cap-table agreement to a new status') with concrete examples of target states (completed after signing, void to retire an unsent draft). An agent can distinguish this from cap_table_update_cap_table_agreement and the other cap-table tools without opening the 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?

Explicit when/when-not guidance: voiding a signed SAFE is refused, and a SAFE with an outstanding signing request must have its envelope voided first. It even dictates failure-handling behavior ('do not retry in a loop') and what to tell the user when the hub is unreachable versus when the SAFE is unfiled.

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