describe_location

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description still adds real behavioural substance — terrain_m is a point reading including water surface/depth, ground and built elevations are sampled from nodes and buildings within radius_m and never averaged, and conduit counts come from the save (zero means none). What's missing is any statement about cost/latency or what happens when the point is outside known data.

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 output inventory is front-loaded in sentence one and the remaining two sentences carry distinct semantics (elevation sampling, conduit counts). It is dense to the point of being cryptic in places — 'their gap is fill already stacked' requires domain knowledge — but no sentence is filler.

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 no output schema, the description takes on the job of describing returns and does so thoroughly (region, terrain, elevations, conduits, nearest node/field). Five optional parameters at 60% coverage leave 'save' and 'world' opaque, and there's no note on behaviour at unknown/empty locations, but the core contract is clear.

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 coverage is 60%, and the description compensates by explaining what radius_m actually does (defines the sampling window for node/building elevations) and by clarifying that conduit results are save-derived counts. The 'at' and 'as_of' parameters are well documented in the schema itself, but 'save' and 'world' remain unexplained in both places.

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 opening sentence enumerates exactly what the tool reports at a location (region, terrain height, sampled elevations, conduits, nearest node/field), which is far more specific than the name alone. It also implicitly separates itself from search_conduits by pointing there for the full list. It lacks an explicit verb framing ('describe/report') and doesn't contrast against near-neighbours like whereami or search_resource_nodes.

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?

Usage is only implied: the reader infers this is the 'inspect one spot' tool from the enumerated outputs, and one alternative (search_conduits) is named for the case where you need conduit listings rather than counts. There is no explicit when-to-use/when-not, and no guidance versus whereami, factory_map, or search_resource_nodes, which overlap in scope.

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