create_map_event

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

With no annotations, the description carries the full burden and does so thoroughly: it explains the blank-page merge model, that omitted `list` becomes code-0-terminated, that structurally invalid command lists are refused (nothing written) unless force:true, that the invisible-wall case is only warned, and that the upper-layer action-button idiom is exempt. This is exactly the validation/refusal/side-effect context an agent needs before writing.

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 purpose, then construction rules, then usage routing, then a field legend — a sensible order. It is a single dense paragraph, however; the validation rules and the page-field legend would scan faster as separate short blocks, and a few clauses are packed tightly enough to slow reading.

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 creation tool with no annotations and no output schema, the description covers creation semantics, merge defaults, validation outcomes, override paths, the advised sibling, and the full page-field vocabulary. An agent has what it needs to both select and correctly invoke it.

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?

Top-level params are already fully documented in the schema, but the nested `pages` items are typed as `additionalProperties: {}` with no property descriptions — the description supplies that missing meaning, enumerating trigger, priorityType, moveType, direction, and image subfields with their numeric values, plus merge behavior for `image`/`conditions`. It adds real value beyond the schema, though it does not cover every top-level field.

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?

Opens with a specific verb+resource ('Create a new event on a map') and immediately distinguishes itself from siblings by naming create_npc as the preferred tool for the talking-NPC case. An agent can tell this apart from update_map_event, set_event_page, and create_npc without opening any 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?

Explicit routing guidance ('For the common "talking NPC" case prefer create_npc'), concrete trigger scenarios ('an action-button page meant to fire from facing... needs priorityType: 1'), and a clear statement of when the tool refuses vs. warns vs. exempts. Alternatives and conditions are all named.

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