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

The description discloses network side effects (image sent to external API), required env vars, and failure modes. Annotations already state readOnly, safe, idempotent, open-world; description adds critical behavioral context without contradiction.

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 fairly long but well-structured with clear mode breakdowns. Every sentence provides necessary info; minor verbosity in the 'ai' mode explanation but overall earns its space.

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 tool with three modes, network side effects, and offline analysis, the description covers all important aspects: return values, failure modes, environment dependencies, and alternatives. No output schema but return format is described per mode.

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 descriptions cover all 5 parameters, but the description adds significant value by explaining mode-specific usage, defaults (resizeMax=1024), and constraints (base64PNG must be raw). This goes beyond the schema's basic descriptions.

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 analyzes images with three distinct modes (ai, grid, colors), each with specific functionality. It distinguishes itself from sibling tool query_map by noting that query_map's 'ascii' view is better for precise map layout.

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?

The description provides explicit when-to-use guidance for each mode, including failure conditions (path escapes, missing file, API timeout) and a clear alternative (query_map for map layout). This helps the agent decide correctly.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, but the description adds valuable context: the in-memory cache invalidates when data files change, formulas are parsed but never executed, unreadable formulas are listed, and search is offline lexical with no synonym expansion. These details exceed the annotation coverage and no annotation contradiction exists.

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 front-loaded with the core purpose and caching behavior, which is good. However, the remainder is a single dense run-on sentence enumerating thirteen views, which harms scannability and could be better structured with bullets or shorter sentences.

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?

Given no output schema, the description fully explains what each view returns—from validate's {issueCount, bySeverity, issues[]} to ast's logical tree and outline. Annotations cover the safety profile, and the schema covers all 15 parameters, leaving no critical gap for correct invocation.

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 coverage is 100%, so the baseline is 3. The description goes further by explaining the semantics of each `view` enum value in detail—what 'validate' checks, what 'metrics' measures, what 'balance' compares—adding meaning beyond the schema's terse enum labels and short parameter descriptions.

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 opens with a precise verb and resource: 'Read-only project intelligence over an in-memory model of the whole project, cached until data files change.' It then enumerates every analysis lens, making the tool's scope unmistakable and clearly distinct from mutating siblings like edit_map or create_database_entry.

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?

The description gives clear guidance on which `view` to choose for each analytical need (e.g., 'validate' for consistency checks, 'metrics' for map measurements), effectively serving as when-to-use guidance for the tool's modes. It does not, however, explicitly name sibling tools or state when not to use this tool versus alternatives like query_map or get_project_context.

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

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

Annotations already declare the safe pure-function profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds substantial context beyond them: no file writes, no project selection needed, the return shape {commands, warnings?}, the end-marker convention for fragments vs branches, and that game-reference validation is deferred to insert time.

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?

Appropriately sized for an 83-parameter tool and front-loaded with the core purpose and routing before the finer MV/MZ semantics. It is a dense single paragraph with no wasted sentence, though the lack of any structural breaks makes the later constraints harder to scan.

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?

No output schema exists, but the description does explain the return value ({commands, warnings?}), which is the key gap it needed to close. Combined with the fragment/branch nesting rules and MV-vs-MZ caveats, it is largely complete for this complexity, though the 46% of undocumented parameters leave some functional territory uncovered.

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 54% across 83 parameters, so the description must compensate, and it does add real cross-parameter semantics: 'kind selects the command; only fields belonging to that kind are accepted,' the troop-only kind list, the MV Show Text four-parameter rule, plugin_command emitting code 356, and the integer-or-decimal-string ID rule. It still leaves many individual parameters undocumented, so not a 5.

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+resource (build an RPG Maker MV event-command fragment) and immediately scopes it against the sibling that actually writes ('without writing files or requiring a selected project'). An agent can distinguish this from insert_event_commands without opening either 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?

Explicitly routes the agent: 'feed commands to insert_event_commands, or nest them in a choice/conditional builder,' which names the downstream alternative and the compose-vs-insert choice. It does not state any when-not condition or prerequisites for this tool itself, so it stops short of a full 5.

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

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

Annotations already cover write/read and idempotency, but the description adds crucial context: immediate file write, automatic ID assignment, preset validation behavior, class params curve expansion, unsupported entities, and lack of ID validation. It omits permission requirements or rollback behavior on batch failures, but provides rich operational detail beyond the annotations.

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 front-loads the core purpose, but the middle section listing all preset fields and edge cases is a long run-on that could be structured better. It remains informative but is not optimally concise.

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?

Given the complexity (4 params, nested data objects, no output schema), the description covers creation modes, ID behavior, validation, and caveats well. It omits what happens if the file write fails or how to handle large batch failures beyond a simple error note, but is largely complete for an agent 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 coverage is 100%, so the schema documents the four parameters well. The description adds significant value by enumerating preset recipe fields, explaining data.name expectations, the 8-stat seed expansion for classes, and the entries batch behavior. It goes beyond the schema's high-level descriptions.

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 the exact verb and resource ('Create a new entry in an RPG Maker MV database'), specifies the ID assignment behavior ('next free ID'), and explains both creation modes (raw vs preset) in detail. It clearly distinguishes itself from update_database_entry and query_database by defining the creation scope.

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?

The description implicitly guides when to use raw vs preset forms and even names query_database as a prerequisite for ID validation ('confirm them with query_database first'). However, it does not explicitly compare against update_database_entry or state when not to use this tool.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), it discloses that the change is written immediately, not undoable, that IDs are never reused, that references are never cleaned up automatically, and that the delete is refused while references exist. It also enumerates every reference category checked and lists the result shape on forced deletes. This is unusually rich behavioral context.

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 front-loaded with the DESTRUCTIVE warning and every sentence carries substantive information with no filler. However, it is a single dense paragraph for a complex topic, and itemizing the reference list or options would have improved scanability.

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, the description supplies the return shape ('Returns the deleted object') and the error behavior ('fails with an error if the ID does not exist'), and it covers the auth/safety profile through both annotations and explicit warnings. An agent has everything needed to call this 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 100%, so the baseline is 3. The description mostly restates schema semantics for id, force, and entity, and it introduces a 'dryRun:true' parameter that does not appear anywhere in the input schema, which is a potential inconsistency rather than added clarity.

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 precise verb and resource ('delete a database entry'), names the mechanism ('nulling it out in its data file'), and lists the exact supported entity types. This clearly distinguishes it from siblings like update_database_entry and create_database_entry without the agent needing to open 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?

It gives explicit conditions for use and non-use: refusal while references exist, fixing references first, using dryRun to preview, or force to override. It also names hard exclusions (never skill 1/2 or state 1). It does not, however, direct the agent to any sibling tool as an alternative, which keeps it short of a 5.

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

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

Goes well beyond the annotations: files are written immediately, fill_layer is destructive and not undoable, missing-map entries are reported in `skipped` rather than erroring for set_display_names, and connect creates bidirectional transfer events. The idempotentHint=true is slightly at odds with event-appending actions like connect, but the description's disclosure quality is high.

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-loads the key mutation warning (immediate write) and then organizes each action as a labeled clause. Dense but every clause carries an action-specific fact; the enumeration could be tighter 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 7-action, 14-parameter mutation tool with no output schema, the description covers each action's semantics, error behavior, and return shape (per-action summary). Nothing critical for correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: layer numbering (0-1 ground, 2-3 upper, 4 shadow, 5 region 0-255), tileId 0 clears, weight default 5, regionSet [] = whole map, and posA trigger semantics.

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 (Modify) and resource (existing maps) and then enumerates each action with its exact effect. It explicitly differentiates from siblings by routing event-level work to manage_map_event.

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?

Per-action guidance is concrete: it names which action to use for which goal, points to get_project_context detail "tileset" for valid tile IDs, and directs event work to manage_map_event. It also states an exclusion (maps have no random battles without set_encounters).

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, and openWorld=false. The description adds substantial behavior: files are written immediately, failures occur on unknown themes/templates or unwritable files, duplicate mode leaves events pointing at original destinations, and non-blank modes return walkability and warnings.

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 opening is front-loaded and useful, but the body is a dense, run-on enumeration of modes and examples. Some details repeat the schema's theme and template enumerations, and the text could be more scannable for a tool with seven modes and twenty-four parameters.

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, the description still covers return shapes such as mapId, seed, markers, walkability, warnings, and batch mapIds. It also states prerequisites, side effects, and failure conditions, making it complete for a highly complex map-generation tool.

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 coverage is 100%, but the mode parameter's schema explicitly says 'see the tool description', so the description supplies essential semantics for mode selection and side effects. It also clarifies cross-parameter behavior for templateId, useTemplate, batch, and duplicate, though other parameter explanations largely mirror 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?

Starts with a specific verb and resource: 'Create a new map file', then states that both the file and MapInfos.json are written immediately. It distinguishes itself from siblings like edit_map and query_map by explaining the creation pipeline and mode-specific behavior without requiring the 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?

Explicitly routes the agent by mode, states prerequisites such as running manage_system action 'mine_templates' first, and names alternatives including edit_map fill_layer and get_project_context. When-not conditions are not exhaustively enumerated, but the mode-by-mode guidance is exceptionally clear.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds valuable behavioral context: warns against inventing tile IDs ('guessing tile IDs produces glitched maps'), explains return types, and details what each mode outputs. No contradictions.

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?

Well-structured with clear ordering: main purpose, detail modes, golden rules. Every sentence adds value, though the description is lengthy due to the tool's complexity. Could be slightly tighter, but still efficient.

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?

Completely covers all aspects: explains every detail mode, parameters, return types, and golden rules for correct usage. Even without an output schema, the description makes it clear what to expect. No gaps for an agent to misuse the tool.

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?

Input schema has 100% coverage, but description adds meaning beyond schema: explains what each enum value of 'detail' returns, and for tilesetId, category, theme, it specifies their role in filtering. Schema defers to description for full semantics.

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?

Explicitly states it is 'read-only: pre-digested project knowledge' and advises 'CALL THIS FIRST'. Clearly distinguishes each detail mode (full, summary, assets, tileset, templates) with specific use cases, differentiating it from sibling tools like query_map and generate_map.

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?

Provides explicit when-to-use instructions: 'CALL THIS FIRST'. Golden rules guide proper usage: use generate_map for maps, never invent IDs, set encounters correctly. Details when to use each detail mode (e.g., 'tileset' for edit_map 'fill_layer').

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

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

Goes well beyond the annotations: it discloses pre-write validation, that invalid data refuses the write, safety rules for explicit positions, fragment rebasing to target indentation, atomic backup-protected writing, unknown vs MZ-only extension command handling, and exactly what the result contains. This is unusually rich behavioral disclosure for a mutation 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?

Content is front-loaded with purpose and validation, then flows into position semantics, dryRun, writer behavior, and return values. It is dense and slightly long, but nearly every sentence carries distinct information and no sentence is pure filler.

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?

Despite having no output schema, the description enumerates the return payload (target identity, insertion count, resulting list length, listCodes, warnings, and verbose before/after lists), so an agent knows what to expect. Combined with the validation and safety rules, nothing needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the safe-boundary constraint on position, the append-before-root-end behavior when position is omitted, dryRun's write-and-backup suppression, and verbose's effect on the result shape.

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 (Insert) and resource (event-command fragment) with explicit scope across three target types (map event page, common event, troop battle page). It also implicitly distinguishes itself from build_event_commands by noting fragments are 'typically returned by build_event_commands', so an agent can tell the two apart without opening the schemas.

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 operational context: omit position to append before the root end marker, use dryRun:true to preview without writing, and pass verbose:true for full lists. It does not explicitly state when to prefer this over sibling writers like edit_map or manage_map_event, which keeps it out of 5 territory.

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

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.

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

With annotations present, the description still adds meaningful behavior: "writes are immediate", backups are "kept in .mcp-backups before every write" with "the newest undoes the last write", MV "ignores ids past it, silently", and prune can lose "assets a plugin names only at runtime". These disclose side effects and failure modes beyond the readOnly/destructive hints, though return shapes and error conditions are largely unstated.

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 definition is a single dense paragraph packing three unrelated topics into the opening sentence and then embedding all 22 actions mid-sentence without line breaks or grouping. While most content is relevant, the wall-of-text structure makes it hard to scan and the front-loaded summary sentence is muddled rather than orienting.

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 22-action, 40-parameter tool with no output schema, the description covers the semantics of most actions and mentions a few return details (`section` values, `lastAuthError`, `relocated`, export file counts). But return values, error behavior and prerequisites for many actions are left unstated, so it is adequate rather than complete for a tool of this scope.

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 there are 40 well-annotated parameters, so the schema carries the semantic load and a 3 is the baseline. The description does add a little cross-action meaning (e.g. the prune caveat, the silent MV id truncation, `relocated` on set_starting_position) but for most parameters it only restates what the schema already documents.

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 names a specific verb+resource for each of the 22 actions (e.g. "set_title sets the game title", "scaffold_project creates a new editor-openable project at destPath"), so an agent can tell what each action does. However, the tool as a whole is a heterogeneous grab-bag and the description never distinguishes it from overlapping siblings such as `run_playtest` or the standalone `take_screenshot` tool, which it partially duplicates.

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?

The description explains what each action does but gives no when-to-use vs when-not guidance and no routing to alternatives. It does not say, for example, why an agent would call action "playtest" here rather than the sibling `run_playtest`, or action "take_screenshot" rather than the sibling `take_screenshot`. Selection is left entirely to inference.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds key behaviors: returns null for missing id (not error), case-insensitive search, description matching for certain entities. No contradictions.

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?

Concise and well-structured: starts with read-only safety emphasis, then enumerates three usage forms, provides usage guidance, and ends with sibling differentiation. Every sentence adds value without redundancy.

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?

Despite no output schema, description explains return types (array vs single object/null) and covers all three modes. Provides complete context for usage, parameter interactions, and relationship to sibling tools. Fully sufficient for an AI agent.

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?

100% schema coverage with descriptions, but description adds crucial semantics: explains that omitting id and query lists all entries, id returns null on missing, query is case-insensitive and also matches descriptions for items/weapons/armors/skills. Significantly enriches understanding.

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 queries RPG Maker MV database files, specifies three forms (list, fetch by id, search), and distinguishes from siblings (query_map, get_project_context). Verb 'query' and resource 'database' are explicit.

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?

Explicitly advises using before create/update/delete operations to discover IDs, and directs to query_map for maps and get_project_context for a full digest. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint and idempotentHint; description adds specifics like failure on missing file, offline nature of ascii view, and validation behavior, adding value beyond annotations.

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?

Efficient and front-loaded with 'Read-only: inspect maps.' Each sentence serves a purpose, but the description is somewhat dense; could be slightly shorter.

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?

Given 7 parameters, 1 required, and no output schema, the description thoroughly explains each view's return format, failure cases, and even provides a cheap way to 'see' layout via ASCII. Complete for the tool's complexity.

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?

While schema has 100% coverage, the description adds meaning by explaining what each view returns (e.g., 'full' returns dimensions and tile data, 'validate' returns issueCount and issues). This compensates for the lack of output 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?

The description clearly states it is a read-only tool to inspect maps, with specific verbs like 'inspect' and lists each view. It distinguishes itself from siblings like edit_map and generate_map by emphasizing read-only nature.

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?

Provides explicit when-to-use for each view and mentions an alternative tool (analyze_image) for player-visible images. Could be more explicit about when not to use, but context is clear.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), yet the description adds real value: capture scope ('only the game canvas, not the desktop or credentials'), the output path, the returned payload shape, and required runtime preconditions.

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?

Four dense sentences with no filler; purpose and the start/stop semantics are front-loaded, and the return payload and defaults follow the core intent.

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?

No output schema exists, but the description compensates by naming the returned fields and save location, and it lists the runtime prerequisites for a non-read-only operation. Minor gaps remain, such as behavior when a capture is already active or how timeoutMs interacts with the defaults.

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 coverage is 100%, so the schema already documents all five parameters with ranges and defaults. The description restates name/fps/bitrate defaults but says nothing extra about timeoutMs, so it sits at the baseline for full schema coverage.

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+resource ('Start or stop recording the live RPG Maker MV playtest canvas') and scopes it precisely via the action enum. It is clearly distinguishable from siblings like take_screenshot or run_playtest.

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 the two modes and lists prerequisites (bridge plugin, running bridge, connected playtest). It does not explicitly contrast with the sibling take_screenshot, so the alternative-selection guidance stops short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely non-obvious behavior: project data is never changed, screenshots land in .mcp-cache/renders/, runs can take minutes, a progressToken is needed for progress, and optional chromium/playwright prerequisites are required. This is exactly the added context annotations cannot carry, and it is consistent with (not contradictory to) the annotation set.

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?

Purpose and safety/execution notes are front-loaded, and the dense semicolon-delimited action catalogue is information-dense rather than padded. The single long step sentence is heavy but each clause earns its place by defining a distinct action; it is appropriately sized for the tool's complexity, if somewhat unwieldy to scan.

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?

Despite covering a complex, multi-action tool with no output schema, the description explains the result shape (each step with ok, a finalState, page problems such as errors and missing files), the prerequisites, and the timing/progress mechanisms. An agent has everything it needs to invoke 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 coverage is 100%, so the baseline is 3, but the description goes further by mapping which fields belong to which action (e.g. load {mapId,x,y,direction?,party?...}, advanceText {maxMs?}, walk {direction,steps?}), a correlation the schema's flat property list does not express. It adds real meaning for a polymorphic steps array, though it does not document every field exhaustively.

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 opens with a specific verb+resource ('Play the game headless from a script of steps') and concretely frames the outcome ('report what happened'), even giving example assertions like door transfers, NPC lines, and choice branches. This clearly distinguishes it from siblings such as take_screenshot, record_video, and analyze_project.

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 gives strong context for when to use it ('no editor or running game needed', headless Chromium boot) and enumerates the exact action vocabulary an agent must choose from. It stops short of naming alternatives or explicit when-not-to-use cases, so it is clear but not fully routing-aware.

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

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

Annotations provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral details: session-wide side effect, path validation (checks for data/System.json), error behavior (fails leaving previous active), and return value (new active path). No contradictions.

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?

Three sentences front-load the purpose, then side effect, then return/alternative. No wasted words; every sentence adds value.

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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, side effects, validation, return value, and the alternative (environment variable). No missing critical details.

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 covers 100% of parameters with a clear description. The description adds validation context (must contain data/System.json) and emphasizes absolute path, which enhances understanding beyond 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?

The description clearly states the tool's purpose: switching to a different RPG Maker MV project directory. It specifies the action (switch), the resource (project directory), and distinguishes from the startup environment variable, making it unique among siblings.

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?

The description explains when to use the tool (to change the project directory) and notes the alternative (environment variable at startup). It implies persistence until changed or restart, but doesn't explicitly mention when not to use it or compare with other tools.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, so the description appropriately adds the details they cannot: authenticated bridge requirement, the 1.5 MB inline-image cap with RPGMV_INLINE_IMAGES=0 opt-out, timestamped per-capture filenames, and the returned shape. It doesn't say where files accumulate over time or whether repeated captures collide, a minor gap.

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 core action, output, and prerequisites are front-loaded in the first two sentences, and nothing is padded. The prose is dense with clauses and parentheticals, but each sentence still carries usable information.

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, the description compensates by naming the return shape {path, bytes, mimeType, name} and the inline image block, plus the full prerequisite sequence. For a 9-parameter tool with two modes (playtest capture vs headless mapId render), the description is largely complete, though the mode split between screenshots/ and renders/ destinations could be stated more cleanly.

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 89%, so the schema already documents all nine parameters including the mapId mode, switches, showEvents, and showPlayer semantics. The description only adds that `name` becomes a safe filename prefix and that captures keep a timestamp, which is marginal added meaning over a high-coverage 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 precise verb+resource scoped to RPG Maker MV playtest frames captured through the MCP bridge, and names the output artifact (.mcp-cache/screenshots/ PNG). It is clearly distinguishable from siblings like record_video, analyze_image, or query_map without opening schemas.

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 an explicit prerequisite chain (manage_system actions install_bridge_plugin, bridge_start, playtest) and notes the compatibility alias manage_system {action:"bridge_screenshot"}. It stops short of stating when NOT to use it (e.g., versus record_video for motion capture), so it falls just under full routing guidance.

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

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

Adds substantial context beyond the annotations: immediate write, no undo, replace-not-merge for arrays, error on nonexistent ID, full-entry return, and cross-cutting side effects (tilesets affect every map; malformed flags break passability project-wide). However, it conflicts mildly with idempotentHint=true, since appendCommand/addEnemyId/addPage are explicitly additive and would duplicate on repeat calls.

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 core partial-update and no-undo semantics, and every sentence carries weight for a 6-param, nested-object tool. It is dense to the point of being a wall of text, mixing core behavior with edge cases in one paragraph, which slightly hurts scannability.

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?

Despite no output schema, it states the return ('the full entry after the update') and the failure mode (error if the ID does not exist), and covers all three special append modes plus entity-specific caveats. 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 coverage is already 100%, so the 3 baseline applies, but the description genuinely adds meaning: that `fields` is unnecessary with the append parameters, that appendCommand picks up build_event_commands output, and that class params accept 8 seeds or 8 arrays of 100 per-level values. This goes beyond restating 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 precise verb+resource+scope: 'Partially update an existing database entry', with the partial/overwrite semantics spelled out (only keys in `fields` are overwritten; arrays replaced wholesale). An agent can immediately distinguish this from create_database_entry, delete_database_entry, and query_database 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?

Gives concrete when-to-use guidance ('fetch current values with query_database first if you may revert') and routes the special append workflows by entity ('common_events + appendCommand', 'troops + addEnemyId/addPage'). It never states a when-not-to-use condition (e.g. use create_database_entry for new entries), so it stops short of the top band.

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