write_graphs

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

Goes well beyond the annotations (which only flag destructive=true): it discloses that writes go into a copy of the save, that graphs are type-checked and compiled before writing, partial-failure semantics ('if one does not compile it stops there', failed names the graph, mapPath holds prior writes), the per-graph size/limits and warnings returned, and a distinct refusal case (SIGNAL_PARAMETERS_DIFFER) with its cause. That is dense, non-obvious behavioral context an agent could not infer from structured fields.

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 action and returned value before the failure and performance details, and every paragraph adds operational value. It is slightly bloated though: the batching rationale is stated twice ('A level of ten graphs is one call instead of fifty' and the thirty-seven-graphs timing anecdote), and the final defineSignal sentence is a long run-on.

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?

There is no output schema, and the description compensates by explaining the return shape (mapPath, editor-counted size per graph, warnings) and the error shape (failed graph name plus compiler errors). For a batched mutation tool with nested objects and no annotation richness beyond destructive=true, 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 description coverage is 0%, so the description must carry the load and it does: graphId is documented as 'a graph that exists in the save' with provenance ('scene_add_graph returned it; inspect_map lists them'), code as 'its whole Genshin-TS source', and mapPath implicitly as the save copy carried between calls for incremental retries. This compensates fully for two undocumented schema properties.

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 and resource ('Write the source of node graphs into a copy of a save') plus the batched shape ('one graph or many in one call'). It also disambiguates from the closest siblings by naming them: 'scene_add_graph returned it; inspect_map lists them' establishes that this tool consumes existing graph IDs rather than creating graphs.

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 explicit prescriptive guidance: 'send all the graphs of a level, or all that changed, in one call' and 'After a change to a few graphs, send only those, on the mapPath that has the others.' It also documents the failure-retry path (repeat with the corrected graph and the ones after it on that mapPath), so the agent knows exactly what to do both before and after an error.

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