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

Annotations already establish read-only, idempotent, open-world, non-destructive, so safety is covered; the description goes further with genuinely non-obvious behavior: the limit applies across all dates, MATCHi may return null anonymous prices that must not be presented as budget matches, and travel time is a straight-line heuristic with 15% soft-filter tolerance rather than live routing. The only real gap is that it doesn't say anything about pagination or provider failure/partial-result behavior across the six providers.

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 use case before the behavioral caveats, and each sentence carries distinct information (price nullability, travel heuristic, player-count semantics, exclusions). It is dense and long for a description, but nothing reads as filler and the ordering follows what an agent needs first.

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 15-parameter, nested-schema, open-world search with an output schema, the description covers the decision-critical behavior: what is searched, how prices and travel are computed, how unknown prices surface, and which siblings to avoid. Remaining gaps are peripheral parameters (radius, court_type, provider, time windows) whose enum/format constraints the schema already conveys.

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?

With only 20% schema description coverage across 15 parameters, the description has to carry weight, and it does explain the semantics of the trickiest ones: limit is global across dates, number_of_players affects per-player price not capacity (with singles_court as the capacity lever), max_price_per_player acts as a ceiling including unknown-price slots, and max_travel_minutes is a soft filter. It says nothing about radius_km, court_type, provider, travel_mode, earliest_time/latest_end_time, or how date vs date_range interact, so several parameters remain undocumented.

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 and resource ('search bookable court options near a UK location on one date or across a bounded date range') and adds scope detail (provider aggregation, price normalization, catalogue venue IDs/coordinates). It explicitly carves out sibling territory ('Do not use for venue-only discovery or public games'), so an agent can separate it from search_clubs and search_public_games without reading schemas.

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?

Opens with an explicit 'Use this when...' trigger, then names two exclusion cases ('venue-only discovery', 'public games') and routes the singles case to a specific parameter. The budget-ceiling/null-price rule also tells the agent how to interpret and present results, not just when to call.

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