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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: the download link is short-lived, exports are gated on a review state, the estimate must be owned, and the incomplete-review branch returns a link instead of a file. These are exactly the behavioral traits an agent needs, and none of them contradict the read-only annotation.

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 sentences, front-loaded with the output artifact and its precondition, then the fallback, then the hard constraint. No filler, and the operative rule ('Never exports unreviewed estimates') is placed last for emphasis.

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 not be enumerated, and the description still discloses the two possible return shapes (XLSX download vs. review link). For a single-parameter export tool the description covers preconditions, eligibility, fallback and constraints completely.

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?

There is one parameter (project_id) at 0% schema description coverage, so the schema contributes no semantic detail and the description compensates with nothing about it — no format, no source of the ID, no note that it must reference an owned project (the ownership constraint is stated only generically). The parameter name is largely self-explanatory, but the description adds no value here.

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 concrete verb ('Get an Excel XLSX download') and a precise resource ('an owned Portravo estimate'), and qualifies it with the exact precondition state (reviewed, priced or final). This is distinguishable from every sibling tool, none of which produce a workbook export.

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?

Explicitly gives the when ('after every takeoff line has been reviewed and the estimate is priced or final') and the when-not with an alternative path ('if review is incomplete, return the Portravo review link and let the user complete quantities, assembly mappings and pricing there'). An agent knows both the gate condition and the fallback without inferring anything.

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