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

Annotations already declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is fully covered. The description adds one genuinely useful behavioural point — that these are voidjet's *own* answers (authoritative policy, not general knowledge) and are limited to company-level topics. It says nothing about whether answers are static, cached, or how current the cost/contract information is, which matters for a fares/contracts FAQ.

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 verb and the fact that these are voidjet's own answers; the two closing sentences carry the usage rule and the exclusion. The middle topic list is a bit of a run-on ('how fast providers reply'), but each item genuinely describes coverage.

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 an output schema present, return values need no explanation; annotations cover safety; and the only optional parameter has a default and a two-value enum. The description completes the picture by defining the topical scope and its boundary against provider/flight data. The locale gap is the sole residual weakness.

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% and the description never mentions the single `locale` parameter or that answers are available in English and German. For a tool whose entire output is prose, the language of that prose is the one parameter an agent most needs explained, and it is left entirely to the bare enum.

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 ('Returns') and a concrete resource (voidjet's own answers on costs, contracts, funding, data recipients, response times), and explicitly carves out what it does not cover: 'No information about single providers or flights.' That negative scope is exactly the territory of siblings like get_empty_leg and search_empty_legs, so an agent can route without opening either 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?

'Use it instead of guessing' gives a clear positive trigger, and 'No information about single providers or flights' functions as an exclusion boundary. It stops short of naming which sibling to call for those excluded cases, so the when-not is implied rather than routed.

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