Fetch kerb segments and car parks

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds genuinely useful beyond-annotation context: the data is 'static', scope is capped at 1.5 km2, hours are only for one date, and prices are absent. It stops short of describing pagination or result-count behavior.

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 sentences with no filler, and the payload (what is returned) is front-loaded before the optional hours and the explicit exclusion. It is dense with parentheticals, which slightly reduces scannability, but every clause carries usable information.

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 12 optional parameters and no output schema, the description carries the output burden and does it well, enumerating entity fields (name, address, WGS84 point, zone, authority, bay types, capacity). Remaining gaps are minor: no mention of result limits/pagination or the relationship between max_results and the two search modes.

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 92%, so the baseline is 3, but the description adds real semantics by clarifying that lat/lng plus viewport and bbox are alternative ways to define the same area and that the 1.5 km2 cap applies to that area, plus that entity_ids replaces area search. This complements individual parameter descriptions rather than restating them.

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?

The description names a specific verb and resource (fetch the static parking map: on-street segments and car parks), scopes it precisely (area point+viewport or bbox up to 1.5 km2, or entity ids), and enumerates returned attributes. It also explicitly differentiates itself from a sibling by stating it does not return prices and routing to find_parking_rules_near.

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?

It gives clear context for the two invocation modes (area search vs entity_ids) and explicitly names the alternative tool for pricing data. It does not, however, distinguish itself from get_parking_entity for single-entity lookups, so the 'which sibling when' guidance is incomplete.

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