query_bounded_region

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

With no annotations at all, the description carries the full burden and does deliver real behavior: a hard 200-system cap on results, explicit marking of systems missing coordinates instead of silent dropping, and the shape of the response (region metadata, provenance-tagged system list, errors). It does not state whether this hits a live EDSM API, whether there are rate limits or latency concerns, or whether the result ordering is deterministic.

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?

Four short sentences, front-loaded with the core purpose, then constraints, then return shape. No filler. Slight redundancy in describing return values that the output schema already covers, but nothing wasteful enough to hurt.

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?

An output schema exists, so the description's return-value sentence is a bonus rather than a necessity, and the cap/null-handling notes are genuinely useful. But for a five-parameter spatial tool with zero schema descriptions, the omission of how to specify the region center is a substantive hole an agent must reverse-engineer.

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% across five parameters, so the description must compensate and largely fails. It never explains the x/y/z vs system_name relationship (two alternative ways to center the region), the default 15 ly radius, whether supplying both is an error, or what units/coordinate frame x/y/z use. Only the word 'sphere' implies radius semantics indirectly.

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: 'Query a bounded EDSM sphere region', plus the notable trait of provenance tracking. An agent can tell this is a spatial-region query against EDSM. However, the sibling tool edsm_sphere_systems exists and the description never distinguishes the two, so the agent must guess which region query to call.

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?

There is no when-to-use guidance, no exclusions, and no mention of the obvious alternative edsm_sphere_systems. The description only hints at implied context (bounded, provenance-tracked) without telling the agent when this beats the sibling or what prerequisites the call has.

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