dd2_scenario

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

With no annotations, the description carries the full burden and does well: it discloses that shelve archives a live slot, that load quits the game when restart=true, arms the save guard and verifies play time, and that the game steals focus during boot. What's missing is the risk side of 'load' – whether it overwrites the current save/progress before unshelving.

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 entity and scope, then action-by-action detail, then slot types, then the focus handoff. Dense but every line carries information; the parenthetical nesting in the 'load' sentence is the only place readability slips.

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?

An output schema exists, so return values needn't be explained, and the description covers actions, prerequisites, side effects and the follow-up handoff to dd2_hand_back. It is nearly complete for a six-parameter mutating tool; only the overwrite behavior of 'load'/'unshelve' on existing saves is left unstated.

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 0%, so the description must compensate and largely does: it maps action to four values, attaches name/slot/area/notes to shelve and name to unshelve/load, and defines restart. The slot-type legend (0 Auto, 1 Last Inn Rest, 2 unmoored, 3 Clear, 4 AddAuto) adds real meaning, though it doesn't say which of the 0-4 range the 'slot' argument accepts when shelving a new entry versus restoring.

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 framing ('Test-harness save scenarios, single slots of the test character unit') and enumerates the four actions it performs. It is clearly distinct from siblings like dd2_saves (actual save files) and dd2_saveguard (the guard itself) because it names the guard as something this tool arms rather than provides.

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 per-action guidance and the key gating condition ('unshelve ... game must be closed'), plus the semantics of restart=true. It stops short of stating when an agent should prefer this over dd2_saves or dd2_launch for a plain launch, so the boundary with those siblings is implied rather than explicit.

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