Flight price calendar

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is added context — which it does well: it discloses that values are cached site minimums that can differ from live results, and that days with no known fare are omitted (no flights, sold out, or not cached). It does not mention rate limits or pagination, but for a calendar endpoint that is a minor gap.

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?

Three short sentences, front-loaded with the core definition, then the workflow, then the caveat. No filler and nothing buried.

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?

Output schema exists, so return values need not be explained; annotations cover safety; the description supplies the provenance/staleness caveat that the structured fields cannot express. An agent has everything needed to call this correctly and interpret gaps in the result.

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 100%, so the baseline is 3; the description adds only the fare basis ('one-adult') and per-day granularity, without format, default, or range guidance (those live in the schema). Not enough added meaning to exceed the baseline.

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+resource+scope: 'Cheapest one-adult fare per day for a route over a date range, in one call.' This cleanly separates it from sibling tools like mb_search_flights (live fare search) and mb_flight_fare_details (single-fare breakdown).

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 to find the cheapest day to fly, then call mb_search_flights for that day' gives an explicit use case plus the follow-up tool. The caveat that values are cached minimums that may differ from a live search effectively tells the agent when this tool is not the right source for an exact/live fare.

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