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

No annotations are provided, so the description carries the full burden and discharges it: metered billing debited from the CALLING agent's wallet, the 400-before-charge wallet-unmoved guarantee, the all-in charged_joules composition, provenance fields on results, and an explicit staleness caveat ('reflect the pin at read time; a held result will not reflect that'). This is exactly the behavioral context an agent needs before a paid call.

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?

Purpose is front-loaded, but the pricing rail is explained twice in different words ('base + 0.5% rail' then 'the base joule_cost plus a 0.5% rail surcharge rounded up'), and the dense backtick-laden prose makes the routing instructions harder to scan than necessary.

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?

There is no output schema and no annotations, and the description still covers pricing, failure semantics, provenance, and per-flag behavior for a 7-parameter tool. It stops short of describing the shape of a returned pin, which is the one gap against a completely self-contained definition.

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%, so the description must compensate, and it does: it enumerates entity_type's four values, explains the id-anchoring interaction, and clarifies the off-by-default flags energy (energy fleet infra) and include_country_centroids (country-centroid placeholders). Those are meaning-bearing semantics the bare schema cannot convey.

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 'Map lane: pins near a point (lat/lng + radius_km)' states a specific operation and resource clearly. However, it never distinguishes itself from the many geographic siblings (nearby, look_at, map_viewport, mapdata), so an agent cannot tell from the text alone why it should pick look_from over `nearby`.

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?

Strong conditional guidance on the entity_type dual behavior ('ALONE filters the frame' vs '+id ANCHORS and keeps ALL types') and explicit routing to billing_quote/joules_balance/joules_deficit with their purposes. What is missing is when-not-to-use guidance relative to the geographic siblings, so it falls short of a 5.

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