imgui_create_scene

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

No annotations are provided, so the description carries full disclosure burden. It doesn't state whether creating a scene that already exists overwrites or errors, whether the scene becomes active immediately, what happens to previously created scenes, or whether window IDs must already exist. For a creation/mutation tool with zero annotation coverage, this is a meaningful 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?

A single efficient sentence with no filler. It conveys the essence without waste, though it could front-load the behavior more explicitly. The conciseness is appropriate for the tool's simplicity.

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 annotations, no output schema, and a mutation-style operation, the description is thin. It doesn't address idempotency, active-state behavior, ordering of windows, or interaction with the scene switch/delete siblings. For an agent that must orchestrate scene workflows across imgui_create_scene, imgui_switch_scene, and imgui_delete_scene, the description provides insufficient operational context.

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%, with both 'name' (Scene name) and 'windows' (List of window IDs visible in this scene) already documented in the schema. The description's phrase 'visible together' adds slight context that windows are multi-selectable as a group but doesn't add semantics beyond baseline 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?

The description uses a specific verb+resource ('Create a named scene') and clarifies the scene's purpose ('controls which windows are visible together'). It distinguishes from siblings like imgui_set_window_visibility and imgui_delete_scene by indicating what a scene represents, though it doesn't explicitly name alternative tools.

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 implies the usage context: a scene governs window visibility as a group. However, it doesn't explain when to use scenes vs. direct visibility control (imgui_set_window_visibility), or whether scenes complement/exclude that mechanism, leaving ambiguity for an agent deciding between approaches.

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