revealed_map

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

With no annotations, the description carries the full behavioral burden and does so richly: it explains fog semantics ('~' revealed but stale, '#' in sight now), what fogged plots remember versus never show, that each reply carries its own legend, and that a Huge map after Satellites is about 10 KB per layer. This is unusually transparent for a read-only map retrieval tool.

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 but front-loaded: it starts with the core output format and layers before moving to fog rules, sizing, and alternatives. Some phrasing is compressed ('Fog rules are the human's'), and the single long paragraph could be structured more scannably, but little is wasted.

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 complex map-retrieval tool with no output schema and no annotations, the description is complete: it describes the return format, every layer, fog behavior, legend behavior, sizing expectations, subsetting and windowing, and sibling alternatives. An agent has enough information to call it correctly.

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. It explains the role of all five parameters: `layers` fetches a subset, and x0/y0/x1/y1 window a large map. It does not spell out default omission behavior or coordinate inclusivity, but the intended use of each parameter is clear.

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 states a specific retrieval resource and its exact output shape: 'The whole revealed map at a glance, as character grids: one string per row (north first), one character per plot, one grid per layer.' It also distinguishes its scope from siblings by naming map_window for one-area reads and map_index for coordinates.

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 routes between alternatives: use this for the whole map, pass `layers` for a subset and x0/y0/x1/y1 to window a large map, use map_window for one area in full, and use map_index for cities, camps, and resources with coordinates. The conditions for choosing each sibling are clear.

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