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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds the important behavioural fact that a third output, the yearly rate, only appears conditionally when months is given, which is not visible anywhere else given there is no output schema.

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 front-loaded sentence with the core computation first and the conditional output last. No filler, no repetition 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?

For a three-parameter pure calculator with full schema coverage, the description covers inputs, outputs and the conditional annualized result. Only minor gaps remain, such as the sign convention if returned is less than cost, which is reasonably inferable.

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 baseline is 3; the description still earns extra by clarifying that months drives an additional annualized-rate output rather than merely filtering the result. It also frames cost as amount put in and returned as the total amount got back, reinforcing the schema wording.

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 computation and its outputs: profit and ROI % from amount invested and amount returned, plus a yearly rate when months is supplied. It is clear enough to distinguish from generic siblings, though it never explicitly contrasts with profit_margin_calculator, which is the nearest neighbour.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named. Usage is only implied by the described inputs and outputs, which an agent must infer selects this tool over profit_margin_calculator or break_even_calculator.

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