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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description does add one genuinely useful behavioral fact: output depends on org-specific discounts and configured prices, so results will differ from list-price estimates. It says nothing about line/month caps, growth modeling, or how missing prices are handled — real concerns for a planning tool with a 25-line, 36-month ceiling.

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?

A single tight sentence with zero waste, and the differentiating clause (own prices, discounts) is placed immediately after the sibling reference. It is arguably too terse for the schema's complexity, but that under-specification is penalized in parameter and contextual scores, not here.

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 and annotations cover return shape and safety, but the input side is a nested workload-line structure with ten fields and three completely undocumented top-level parameters. For a planning tool whose correctness hinges on building valid lines (model plus calls/tokens/units), one clause of prose is not enough for an agent to call it correctly.

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 description coverage is 0% at the top level: 'lines', 'months', and 'growth_pct' carry no descriptions anywhere, so the description must compensate and does not. Nothing explains that a line is a per-model workload entry (calls, tokens, units, batch, variant), nor what months and growth_pct do to the projection. Only a few deeply nested Line fields have inline descriptions, which the top-level prose never touches.

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 precisely what this tool does relative to a known sibling: it projects costs using the organization's own negotiated discounts and configured prices rather than list prices. That contrast makes it distinguishable from simulate_workload. It stops short of a full verb+resource statement (nothing says it produces a multi-month, multi-line cost plan from a workload spec), so it is clear but not complete.

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?

By framing itself as 'like simulate_workload, but at the organization's own prices,' it names the alternative and the condition that selects it — an agent can route between the two without opening either schema. It gives no guidance against other cost-adjacent siblings (get_spend, forecast_spend, compare_models, list_your_prices), so exclusions are absent.

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