Change a map's own settings

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

Annotations give idempotentHint=true and destructiveHint=true, yet the description adds real context beyond them: encounters are replaced wholesale unless clearEncounters is set, and the size omission is justified by corruption risk ('a wrong array length corrupts the map'). This discloses overwrite semantics and a danger the annotations only hint at.

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?

Front-loaded with the scoping statement and field list, then the detail that matters (encounters). Every sentence carries content, including the closing size rationale, though the description is dense and could trim the field enumeration slightly.

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 required and a single required param, the description covers the complex nested encounters logic, the destructive replacement behavior, and the deliberate omission of resizing. A twenty-three-parameter tool could still say more about the non-encounter fields, so not full marks.

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 only 13%, so the description must compensate. It does so for the hardest parameter, giving the encounters shape ([{regionId, troopId, appearances}]), the regionId=0 whole-map convention and its link to layer-5 regions painted by set_tiles, and the weight meaning. It also maps the other field groups by name, though per-field details (scrollType, encounterStep units) are left to the schema.

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 (Set) and a precisely scoped resource, then defines it by exclusion: 'map-level fields that are not tiles and not events.' The enumerated field list (display name, tileset, banner, dashing, battlebacks, parallax, BGM/BGS, encounter table) lets an agent separate this from set_tiles, set_event_page, and patch_database_entry without opening a schema.

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?

Explains why the tool exists ('Encounters are the reason this exists — list_maps reports them, and without a writer a playtest can be built that never meets a monster'), which tells the agent when it is needed. Names alternatives implicitly: set_tiles for painting regions, create_map for sizing, list_maps for reading. No explicit when-not beyond sizing, so not a full 5.

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