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

Beyond the annotations, the description discloses critical side effects: correctedTerms creates a new commercial revision linked to the episode, an old reversed episode stays reversed, and the current deal outcome remains unchanged. It also reveals the zero/missing-value acknowledgement requirement and adds a security-relevant behavior note about treating CRM field values as untrusted data. This is materially richer than the annotation set alone, and consistent with idempotentHint=true.

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 description is dense but efficiently organized: purpose first, then constraints, exclusions, idempotency requirements, and a final security note. Every sentence contributes meaning, and the length is justified given the tool's complexity. It is not bloated, though the density makes it slightly harder to parse than a bulleted structure would be.

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?

Given the complexity (22 params, deep nested objects, no output schema), the description covers the core semantics, exclusions, prerequisites, and idempotency behavior well. The main gap is that it does not describe return values or failure/conflict behavior (e.g., what happens on a stale expectedUpdatedAt), and several parameters remain semantically unexplained. Still, the most decision-critical behaviors are disclosed.

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?

With schema description coverage at only 5%, the description carries the burden and meaningfully explains the key parameters: correctionReason (required), expectedUpdatedAt/expectedLifecycleRevision (current revisions), correctedTerms (replaces final terms, requires acknowledgements), actualAmount (mutually exclusive), and idempotencyKey (fresh, retry semantics). However, 22 parameters exist and many remain unexplained — outcome, finalTerms, targetStageId, winReasonCode, lossReasonCode, reversalReason, actualCloseDate, and the acknowledgement flags are all undocumented in both schema and description.

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 — 'Correct facts on an explicitly identified deal closure episode' — and precisely scopes it as an episode-level correction rather than a general update or close. It distinguishes itself from siblings by naming what it is not (reopen_record) and by defining the two distinct correction modes (correctedTerms vs actualAmount).

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 description gives explicit usage boundaries: 'Use reopen_record to change current outcome', explains when correctedTerms applies (active won closure) vs actualAmount (scalar amount of any episode), and warns that correctedTerms cannot accompany actualAmount. It provides idempotency guidance ('Reuse that key only to retry the same intended action') but does not address alternatives like update_record or save_deal_commercials.

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