list_areas

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains that the tool lists geographies, returns id and name, and always pairs id with the same country. It does not explicitly state the operation is read-only, but the verb 'List' and the absence of any mutation language strongly imply it, and the description adds useful context about ID usage with query_data. A score of 4 reflects good transparency for a simple list tool.

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?

Every sentence earns its place. The description leads with the core purpose and then efficiently covers defaults, country-specific differences, examples, and a pointer to query_data. No fluff or repetition; it is dense but well-organized.

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?

The tool is simple (2 optional parameters, output schema exists), and the description covers all needed decision points: default levels per country, available levels, how the output IDs connect to query_data, and the requirement to pair ID with the same country. There is nothing an agent needs to know to invoke the tool correctly that is missing.

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 0%, so the description must fully compensate for parameter documentation. It explains both parameters in depth: `level` is described with defaults, country-specific primary levels, and examples of other possible values, and `country` is explicitly limited to 'ireland' or 'united-kingdom'. It also tells users where to find valid levels per dataset (compatible_levels from query_data), going far beyond the raw schema.

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 opens with 'List every geography at one boundary level, for one country', which states a specific verb and resource. It further distinguishes itself from siblings by explaining that it returns area IDs used by query_data's area-scoped modes and directs users to query_data for compatible levels, making the purpose unmistakable.

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 clearly implies when to use this tool—when you need to enumerate geographies or obtain IDs for query_data—and references query_data for dataset-specific levels. While it does not explicitly say 'use X instead' or provide when-not-to-use exclusions, the relationship to query_data and the level guidance provide clear context for choosing it. It earns a 4 rather than 5 because the when-not guidance is implicit rather than explicit.

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