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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: that fallback numbers are example assumptions explicitly labelled for replacement, and that the calculation is driven by specific input pairs. It does not mention rate limits or output format beyond naming the sections.

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?

Two sentences, front-loaded with the action, then the value-derivation rule, then the deliverables. Dense but each clause carries information; only mild awkwardness ('when you give them', 'labelled for you to replace') slightly hurts readability.

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 14-parameter, no-output-schema tool, the description supplies the key missing glue: how inputs map to the value calculation, what happens with incomplete input, and what sections come back. It does not describe the shape or size of the returned case, which would help an agent set expectations.

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 100%, so the baseline is 3, but the description adds cross-parameter precedence logic the schema states only in isolation: annual_value_estimate takes priority, with current_annual_cost + expected_improvement_percent as the alternative path. That precedence rule is real added meaning beyond the per-field descriptions.

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 artifact ('Build an ROI business case') and immediately names the outputs produced (ROI, payback, executive summary). The resource is unique among siblings (all other tools are coaching, scripting or writing tools), so an agent can distinguish it without opening the schema.

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?

Gives clear conditional guidance on when the value figure is buyer-supplied versus when benchmark/example assumptions are used, including the exact parameter combinations that trigger each path. It does not explicitly compare itself to sibling tools or state prerequisites, but the context of use is unambiguous.

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