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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses the pre-onboarding hold behavior, points to list_pending_client_progress to observe held values, and explains that the call previews unless confirm:true. Remaining gaps are what happens to the source report after promotion (status change or retention) and whether repeated calls are idempotent.

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 short sentences, front-loaded with the action and destination, then the onboarding edge case, then the confirm gate as a trailing parenthetical. No filler or repetition of the tool name.

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 two-parameter mutation with minimal annotations and no output schema, the description covers the precondition, the side effect, the edge case, and the safety gate. Return-shape details are unnecessary since no output schema exists and the preview behavior is already characterized.

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 reportId has no schema description at all, so the description must compensate. It does so partially by constraining reportId to a NEEDS_REVIEW health report (a real semantic constraint beyond type:string) and by restating the confirm preview/execute semantics in prose. It does not explain the format of reportId or how to obtain one.

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?

"Promote a NEEDS_REVIEW health report's extracted values into the client's progress timeline" gives a specific verb (promote), a specific resource (extracted values from a health report), and a specific destination (progress timeline). An agent can separate it from upload_client_health_report or list_client_health_reports by the destination and the NEEDS_REVIEW precondition, though no sibling is named as an explicit alternative.

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 states the condition that makes this tool applicable (the report must be in NEEDS_REVIEW) and the confirm-gating flow, which is the key operational decision for the caller. It also flags an edge case: calling before onboarding completes is valid because values are held. It stops short of naming when to use a sibling instead (e.g., delete_health_report for rejecting a report instead of promoting it).

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