play_scene

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds behavioral context: after playing, the tool waits for play_started condition and logs_read for errors, suggesting it initiates playback and monitors for success. This goes beyond annotations by detailing execution flow and side effects.

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 two sentences, front-loading the core action, then efficiently covering options and follow-up steps. Every sentence adds value, and there is no redundancy or 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?

Given no output schema and two parameters, the description adequately covers the tool's behavior and parameter usage. It also integrates related tools (wait_until, logs_read) to suggest a complete workflow. Minor ambiguity about whether the tool blocks or returns immediately, but overall sufficient.

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 only 50% (scene has description, current does not). The description compensates by clearly explaining the semantic roles: scene path for specific scene, current=true for open scene, and omission for main scene. This adds meaningful context that is not fully captured in 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 plays a scene in the editor, with explicit modes for specific scene, current scene, and main scene. The verb 'play' and resource 'scene' are unambiguous and distinguish it from siblings like 'open_scene' and 'stop_scene'.

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 each parameter option (scene path, current boolean, default main scene). It also mentions the follow-up actions (wait_until and logs_read), providing implicit guidance on the expected workflow. However, it does not explicitly contrast with alternatives or state when not to use it.

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