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

Goes well beyond the readOnly/non-destructive annotations: discloses that oversized views coarsen cells without dropping positions, explains what total vs groupCount count, gives the 50-group page cap, and warns that bounds/centers/counts describe groups, not individual containers. That last note heads off a real misuse.

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?

Dense but front-loaded: purpose and constraints come first, drill-down routing and paging follow. Minor waste in the closing 'Coverage and historical-evidence limits are unchanged,' which is opaque without prior context.

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 an output schema present, the description wisely explains the two count fields and paging rather than return shapes. The one gap is the vague closing sentence about coverage/historical-evidence limits, which an agent cannot act on without outside knowledge.

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?

Although top-level schema coverage reads 0%, the nested properties are richly documented and the description adds constraint-level meaning: cellSize must be a power of two (and may be coarsened), all four bounds must be supplied together, and query.limit caps at 50. It works alongside the schema rather than duplicating it.

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 ('Get spatial aggregates of captured Find positions') and immediately distinguishes itself from search_world_find by noting it reuses the same filters but aggregates them. An agent can tell this is the map/aggregate variant vs the per-result search variant.

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?

Explicit prerequisites are given (four viewport bounds, power-of-two cellSize) and the drill-down path is named: 'Use representative XYZ with get_world_find_history or search a group's bounds for its members.' Paging is also prescribed ('follow nextOffset with unchanged filters').

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