scene_list_interface

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the trailing 'Read-only' merely restates them. What the description does add beyond the annotations is the shape of the result (nested clientInterfaces with per-control Lua scripts), but it discloses nothing about defaults, pagination, failure modes, or how the save/map is resolved.

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?

One dense sentence, front-loaded with the verb and result scope, followed by a short safety tag. It is long but every clause enumerates a distinct returned category, so little is wasted; the controls list could be tightened slightly.

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 does useful work by sketching the return structure (built-in HUD pieces vs. custom controls vs. clientInterfaces trees with Lua scripts). But for a tool whose only parameter is undocumented and whose output is a nested tree, missing details on mapPath resolution and result size/shape leave real gaps.

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% for the single optional mapPath parameter, so the description carries the full burden — yet it never mentions mapPath or explains which save/map is read when it is omitted. 'Of a save' is the only hint, and it does not resolve the default-behavior question an agent must answer before calling.

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 and resource ('List the screen layouts of a save and the controls on each') and enumerates the content types returned (HUD pieces, progress bars, text boxes, timers, scoreboards, containers, clientInterfaces trees with Lua scripts). This clearly separates it from siblings such as scene_list_components or scene_get_client_ui, though it never names an alternative directly.

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?

Usage is only implied: 'List the screen layouts of a save' plus 'Read-only' suggests an inventory/inspection use case. There is no explicit statement of when to prefer this tool over scene_get_client_ui, scene_list_client_scripts, or editor_preview_interface, nor any exclusions.

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