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

Annotations only declare openWorldHint=true, which is not very informative. The description compensates by disclosing scope limitations (China-only, specific point required, not city-level), what data it returns (indices and descriptions, not detailed lists), and what it excludes (household registration counts, POI names/coordinates). It clearly communicates it is a data query tool returning analysis rather than raw statistics. No contradiction with annotations.

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 somewhat lengthy, especially the list of excluded indicators and examples which could be trimmed. The core purpose is in the first sentence, but the pricing JSON and repeated exclusions add bulk. It is structured and front-loaded but includes redundant details (e.g., repeating China-only restrictions in both description and parameter schema).

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 tool has an output schema, return values are documented separately. The description covers input constraints, data types, exclusions, and examples comprehensively. With openWorldHint as the only annotation, the description effectively carries the behavioral burden. It is complete enough for an agent to correctly invoke it without further clarification.

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% with both parameters well-documented (city without 市 suffix, address with hierarchical structure rules). The description adds extra examples of valid address forms and reinforces the address scope constraints (China-only, no city names as address). It also clarifies the address format requirement beyond the schema alias example.

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 the tool queries population analysis near a specific Chinese address, listing the three indicator types (人口结构, 居住密度, 商务密度) and explicitly excluding non-target data (户籍统计, 人口名单). It distinguishes from sibling tools like cbd_surrounding_consumption and cbd_surrounding_housing by specifying only population/density indices, not consumption or housing details.

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 specifies valid address types (门牌、地标、路名、小区名、园区出入口) and invalid ones (市名, 区县名, 境外地址), with typical question examples. It does not explicitly name alternative tools for other surrounding analyses, but the examples and exclusions provide clear usage context. No explicit 'when not to use' beyond scope exclusions, so a 4 is appropriate.

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