Discount / sale price calculator

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description's real contribution is computational behavior: stacked percents multiply, tax/VAT is applied after discounts, and money is rounded to the cent at each step like a till. Those rules materially affect results and are not in the schema. Return shape is only loosely sketched ('what you save', 'effective total discount').

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?

Front-loaded one-line summary followed by three compact mode clauses; nearly every phrase carries information. The trailing web-version URL is marginally useful context rather than tool-selection content, slightly diluting an otherwise tight description.

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 14 optional parameters and no output schema, the description does a good job mapping parameters to modes and hinting at returns (savings, effective total discount, cheaper-per-unit winner). It never gives an exact result shape for compare mode (e.g. per-unit prices for A and B), which is the remaining gap.

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 per-parameter text is already handled (baseline 3). The description adds ordering semantics the schema cannot express: the second discount applies after the first, percents stack multiplicatively, and tax is added after discounts. The compare example ('0.5 for 500 g when unit is kg') also clarifies unit/amount relationship.

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?

Opens with a concrete framing ('Three shop maths jobs') and then names each mode with a specific computation: sale price after stacked discounts plus tax, reverse discount percent between two prices, and per-unit deal comparison. An agent can tell exactly what this does and how it differs from generic siblings like calc_percentage or calc_split_bill.

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?

Each mode is prefixed with its purpose ('sale:', 'reverse:', 'compare:'), which effectively tells the agent which mode to pick for which question. There is no explicit when-not guidance or named alternative tool (e.g. vs calc_percentage), so it stops short of a 5.

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