manage_map_event

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

Annotations declare destructiveHint=true and non-idempotent, and the description corroborates with 'the map file is written immediately' and 'delete removes it (destructive)'. It also discloses behaviours annotations could not: missing destination/troop/item/switch are refused, unwalkable or occupied tiles are still created but reported in `warnings`, and create/update/convert/delete vs. append semantics differ per action. Minor gap: it doesn't state permissions or whether changes are reversible.

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?

It is one enormous run-on sentence-plus-prose block that front-loads the verb but then buries every preset recipe, refusal rule, and action semantic in a single dense paragraph. It is informative but poorly partitioned; scanning for a specific preset or action requires re-reading the whole block, and a bullet/table structure would serve the agent far better.

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 36-parameter, high-complexity mutation tool with no output schema, the description covers the essential decision space: which action to pick, what each preset builds, update vs. overwrite-only-fields, convert's preserved vs. replaced attributes, delete's destructiveness, and the warnings channel. What it omits – return value shape beyond 'events with ids', authorization/rate-limit context – is minor given annotations and schema coverage.

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 100% and the schema already documents each parameter, including the enum meanings for action and preset and the shape of nested goods/items. The description restates the per-preset payload shapes (npc, chest, shop, door, puzzle_switch, boss) and adds cross-references like create_database_entry preset encounter_troop and manage_system get switches, but this largely echoes structured data, so baseline 3 applies.

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 set plus resource ('Create, change or remove map events') and immediately names the file side effect. It also enumerates every action verb (create/update/convert/delete/add_command/populate) and every preset recipe, so it is unmistakably distinct from siblings like edit_map, generate_map, and insert_event_commands.

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?

Gives clear conditional guidance throughout: when to omit `preset` vs. supply one, when to follow a bare event with add_command/insert_event_commands, what 'convert' preserves vs. replaces, and what 'populate' scatters. It notably routes the agent toward the sibling insert_event_commands, but it does not contrast itself against edit_map or query_map view 'events' for locating event ids beyond one passing mention.

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