catchment_pois

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

No annotations are present, so the description must cover behavior. It mentions that categories are enum-constrained (no free-text queries) and gives units, but does not address rate limits, errors, or how results are grouped. The output schema exists but is not referenced.

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?

The description is extremely concise: two sentences plus a code example, front-loaded with the main purpose. Every sentence adds value, and the example illustrates usage effectively.

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?

Given the output schema exists, the description focuses on inputs. It covers the core idea and units, but lacks details on parameter constraints (e.g., lat/lon ranges, max minutes, max categories) and does not clarify how it relates to sibling tools like isochrone.

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 only 20%, so the description should compensate. It only adds that categories are enum-constrained (already in schema) and shows an example. It does not describe lat, lon, minutes, or mode beyond the example, leaving gaps in parameter understanding.

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 clearly states that the tool returns points of interest inside a site's catchment, grouped by category. It provides specific details like units (decimal degrees, minutes) and an example, which helps distinguish it from siblings like geocode or isochrone.

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?

The description implies usage for obtaining POIs within a catchment area but does not explicitly state when to use this tool over alternatives like isochrone or site_reach_score. No when-not or exclusion criteria are provided.

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