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 bar is low. The description still adds real business context the annotations cannot: pricing is list price, EUR, excluding VAT, licences are perpetual and one-per-computer with all drivers and no device/tag limits, and the first year of updates is included. It does not say whether the response is itemized or what fields come back, which matters since 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?

Front-loaded with the core definition, then constraints, then the escalation path — dense and mostly waste-free. A few phrasings are compressed to the point of ambiguity ('offer request_demo then'), costing a little clarity.

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 5-parameter read-only pricing tool with no output schema, the description covers scope, pricing rules, exclusions and the alternative tool. What is missing is a sense of the returned shape (itemized breakdown vs. single total) and how module pricing combines, which an agent might need to interpret results.

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 60% and the description compensates meaningfully: it constrains 'modules' to specific product contexts, ties 'computers' to one licence each, and clarifies 'maintenance_years' as years bought after the included first year. The modules wording ('SCADA and Embedded only') is somewhat opaque against enum values quality_maintenance/energy and could confuse an agent, but the added meaning clearly exceeds the schema.

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 precise verb and resource ('Calculates the list price of PLCGateway licences') plus the currency (EUR) and VAT treatment, which are the defining attributes of a quote. An agent can easily tell this apart from product_info (information lookup) and request_demo (commercial follow-up).

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 names the exclusion case and routes it to an alternative: 'Embedded and Enterprise are priced on request: offer request_demo then.' That is a clear when-not plus alternative. The remaining gap is no guidance on when to prefer this over product_info for descriptive vs. price questions.

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