analyze_spatial_geometry

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

With no annotations at all, the description carries the full disclosure burden and falls short. It never says whether the tool performs an external EDSM query (the 'bounded EDSM sphere' phrasing hints at it), whether it is read-only, what happens when no coordinates are supplied, or how expensive/latent the computation is.

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?

Two sentences, front-loaded with the core action and followed by a compact enumeration of computed metrics. No filler; the only inefficiency is that the parameter mechanics get no space at all.

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?

For a five-parameter analysis tool with zero annotation coverage and no parameter documentation, the description leaves critical operational questions unanswered: what defaults to (e.g., whether x/y/z fall back to the current location), whether system_name overrides coordinates, and whether results are computed locally or fetched from EDSM. The existing output schema covers return values, but that is the only area adequately handled.

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 does not. 'Bounded EDSM sphere' weakly implies x/y/z plus a radius, but nothing explains the default radius_ly of 15, the optionality of every argument, or the relationship between system_name and the raw coordinate pair.

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 ('Analyze geometric structure of systems') and enumerates the exact metrics produced: linearity, planarity, spread, centroid, compactness, and nearest-neighbor statistics. That distinguishes it from generic listing tools like edsm_sphere_systems, though it never names the nearby analytical siblings find_spatial_clusters or spatial_sensitivity_analysis.

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 listed outputs ('identify linear arrangements, planar structures, or spherical clusters') imply the analytical question this tool answers, which is more than nothing. However, there is no explicit when-to-use statement, no guidance on when find_spatial_clusters or spatial_sensitivity_analysis would be preferred, and no prerequisites or exclusions.

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