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

Annotations only declare non-read, non-destructive, closed-world. The description adds real behavioral context: canonicality (a shared backend action, trust returned actual_tool_output instead of a state-recovery call), idempotency posture (obey the retry key, otherwise re-inspect state), and a confirmation boundary. The confirmation sentence is generic boilerplate whose 'this read' phrasing sits awkwardly against readOnlyHint=false, but the substantive disclosures are genuine value beyond the annotations.

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?

The purpose and prerequisites are front-loaded and the labeled sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) are scannable. The trailing 'Confirmation boundary' sentence is a long disjunctive template that mixes read/save/pre-authorized cases and is not tailored to this mutation, so it dilutes rather than earns its space.

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 governed mutation with no output schema, the description covers the governance frame (options lookup, departure linkage, approval signatures being separate, auth prerequisite) well. It is thin on the actual mechanics an agent needs: what each parameter means, what 'linked' implies, and what a successful proposal returns or triggers.

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 description coverage is 0% across 8 parameters, so the description must carry the load. It only indirectly signals kind ('officer or director') and replacementCaseId ('provide the completed departure case'), and says nothing about title, email, companyId, idempotencyKey, or the nested _corply_context receipt object. Half or more of the parameters remain opaque.

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?

The description states a specific verb and resource ('Propose a linked officer or director appointment') and scopes it to 'a Corply-formed or governance-reviewed imported Delaware C corporation'. It also distinguishes the occupied-office branch (requires a completed departure case) from the sibling propose_governed_departure. It does not, however, draw the line against record_company_director_appointment, which appears to be a very close sibling.

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?

It gives explicit sequencing ('Call list_governed_action_options first to resolve import evidence gaps') and a conditional requirement ('For an occupied office, provide the completed departure case'), plus an auth prerequisite. What is missing is when an agent should pick this tool over record_company_director_appointment or create_departure_package.

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