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

With no annotations provided, the description carries the full burden and does so richly: it discloses auth requirements (agent keys only, non-agent refused before charge), rate window, metering/debit from calling agent's wallet, pricing (one basic price, rail surcharge), and the critical sampling behavior (pins are a sample, counts are true totals). It also discloses source_tier/tier_label per pin and the honesty semantics matching look_from.

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 description is dense and information-rich, front-loading the core purpose before diving into params and billing. It is long, but every sentence earns its place given the tool's complexity and the absence of annotations; the structure is logical: purpose, params, return semantics, auth, metering, and per-pin fields.

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 7-parameter tool with no annotations and no output schema, the description is remarkably complete: it covers all parameters, return shape (pins, counts_by_type), the critical sample-vs-total distinction, auth, rate limiting, metering, pricing, and per-pin fields. Nothing an agent needs to call it correctly is missing.

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 explains min_lat/min_lng/max_lat/max_lng as the bbox all four together, entity_type with the allowed values (deposit | infrastructure | company | project) and default, energy default False and what it omits, and include_country_centroids default False. This adds meaning far beyond the bare schema titles.

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 description clearly states the tool maps a bounding box to the screen, relays GET /api/v1/map.viewport, and lists the typed parameters. It distinguishes itself from siblings like look_at, look_from, and nearby by emphasizing the bbox/screen framing and the capped pins plus counts_by_type behavior.

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?

It explicitly says when to use this tool (everything inside a bounding box, the screen) and contrasts with alternatives like look_from for honesty semantics. It also gives clear parameter usage guidance: all four bbox params together, entity_type defaults, energy default, include_country_centroids default.

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