scene_item_index_setSet the z-order position of a scene item in OBS, where index 0 places it at the bottom. Use to arrange overlapping items by assigning a new index.
Set scene item z-order. OBS index 0 is the bottom.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| sceneId | No | OBS scene UUID. | |
| sceneName | No | OBS scene name. | |
| sceneItemId | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| error | No | ||
| result | No |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read-only, non-idempotent mutation, and the description adds useful coordinate semantics: index 0 is bottom. It does not disclose side effects on other items' z-order or behavior when the index is out of range. No contradiction with annotations exists.
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 one efficient sentence plus a clarifying coordinate note. It is front-loaded with the operation and contains no filler or redundant restatement of the title.
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?
For a simple reorder mutation with an output schema and annotations, the description covers the core semantics. The main remaining gap is optional sceneId/sceneName disambiguation and index bounds, but these are not severe enough to make the tool unusable.
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 only 50%, and the required parameters sceneItemId and index lack schema descriptions. The description adds meaning to index by tying it to z-order and bottom position, but it does not clarify how sceneItemId is obtained or whether it is scoped to a scene.
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 and resource: 'Set scene item z-order.' This clearly identifies the operation and distinguishes it from sibling tools like scene_item_transform_set or scene_item_enabled_set, which affect other scene-item properties.
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 clarifies how to interpret the index value ('OBS index 0 is the bottom'), which is useful usage context. However, it does not explicitly say when to use this tool, when not to, or that scene_item_list should be used to obtain sceneItemId values. There are no direct sibling alternatives for z-order, so the gap is mild.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.