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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds what they cannot: that the call is free and side-effect-free ("Pure and free"), that it can be invoked repeatedly, and that its suggested cap is advisory rather than an enforced spend limit. That last point is a genuinely important semantic distinction an agent would otherwise get wrong.

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 returned artifacts are front-loaded, and each following clause carries a distinct decision-relevant fact (freedom to re-call, re-quote trigger, cap authority). No filler or restatement of the title.

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?

With no output schema, the description does the work of describing the return payload (estimate items, range, suggested cap, balance, quote_id) well. The one remaining gap is sequencing: it never states whether a plan must exist first (build_plan/get_plan before quote), which matters for an agent orchestrating these siblings.

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 0% for the single project_id parameter, so the description must compensate. It implies project scoping ("remaining work on a project") but never states the identifier format or that project_id comes from list_projects, leaving the agent to infer sourcing.

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 specific verb and resource (itemized cost estimate for the remaining work on a project) and enumerates the cost lines it covers (casting, storyboard, shoot, score) plus the returned artifacts (range, suggested cap, balance, quote_id). This is clearly distinguishable from siblings like greenlight and build_plan, which the description also names.

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 licenses repeated use ("call as often as useful while negotiating scope") and states the re-quote condition ("If the plan or settings change, quote again"). It also routes the spending decision to the sibling tool, clarifying that the cap set at greenlight, not this estimate, is the boundary.

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