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

Annotations indicate readOnlyHint=false and idempotentHint=false, suggesting potential side effects. The description adds critical behavioral context missing from annotations: the '(1 credit)' cost and that it 'Returns a detailed rationale.' However, it doesn't clarify the implications of idempotentHint=false (whether retries cost multiple credits) or what happens if invalid IDs are provided.

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?

Four sentences efficiently structured: purpose with cost upfront, parameter source explanations, and return value description. Every sentence provides distinct value (cost info, parameter provenance for both params, return type). No redundancy with schema or annotations.

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 no output schema exists, the description compensates by stating it 'Returns a detailed rationale for the recommended change.' It covers the credit cost and workflow integration. Could improve by mentioning error scenarios (e.g., invalid change_id) or retry behavior given idempotentHint=false, but adequately complete for a 2-parameter consumption tool.

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 100% schema description coverage, the baseline is 3. The description elevates this by adding semantic context about parameter provenance—specifically which sibling tools generate the required IDs—and provides concrete examples for change_id ('e.g., '1', '2''). This workflow context goes beyond the schema's technical definitions.

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 clearly states the tool 'Get[s] a detailed explanation of a specific edit from a positioning review' with specific verb and resource. It distinguishes itself from generic retrieval tools by specifying it concerns 'positioning review' edits and explicitly notes the '(1 credit)' cost, differentiating it from free lookup operations.

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 explicit workflow guidance by stating exactly where parameters originate: 'change_id comes from the edits array returned by ceevee_confirm_lens or ceevee_full_review' and 'cv_version_id from ceevee_upload_cv or ceevee_list_versions.' This creates a clear dependency chain with sibling tools, telling the agent precisely when to invoke this tool (after obtaining edits from those specific sources).

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