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 profile is covered. The description still adds real value beyond them: 'detail'=true yields a 'larger answer' (a cost/size hint) and the counts are 'mapped venues, not a quality measure', which prevents misinterpreting the numbers. It stops short of noting result size limits or ordering.

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?

Four compact sentences, front-loaded with what is listed, followed by the sibling exclusion, then the parameter behavior. Every sentence carries new information; nothing is padding.

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?

No output schema exists, so the description must describe the return shape — it does: cities/metro areas with venue counts, grouped by country, optionally split per sport. Combined with the caveat about what the counts mean and the pointer to search_courts, an agent has everything needed to call it correctly.

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 schema already documents both parameters, including the ISO-code option and the hidden-private counts. The description's 'country (e.g. Spain)' and 'detail=true adds per-city counts by sport' largely restate the schema, adding only the 'larger answer' framing.

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 ('List the covered cities and metro areas with the number of venues in each, grouped by country'), including the unit of aggregation. It also explicitly distinguishes itself from the sibling search_courts, which lists courts, so an agent can pick the right tool 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?

Gives explicit routing: 'It does not list courts: to find courts, call search_courts with city=<a name from this list>', which even describes the correct handoff workflow. It also states how to narrow with country and when to opt into detail, so both usage modes are covered.

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