Stage Gestures

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

With no annotations, the description carries the full behavioral burden and adds real context: it explains row ownership (engine, person, scene; locked and fixed rows are the engine's), reports collisions, and discloses that saved values which cannot be used are IGNORED and the engine's value stands. That is meaningful behavioral detail beyond a bare query. It still does not explicitly state that the operation is read-only or whether it requires a running VR scene.

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 content is relevant and front-loaded, but it is delivered as one long run-on sentence joined by 'and'/'then', which makes it dense to parse. The enumerated shape list earns its place, but the overall structure would benefit from breaking the ownership, collision, and ignored-value clauses into separate sentences.

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 the description need not explain return values, and it covers the conceptual contents of the gesture map plus the sibling alternatives well. However, for a tool with 0% parameter description coverage, the absence of any explanation for 'scene' and especially the optional 'scenes' parameter leaves a meaningful completeness gap.

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% and there are two parameters, yet the description never mentions 'scene' or 'scenes' explicitly or explains their relationship. 'For this scene' hints at the required 'scene' parameter, but the optional 'scenes' parameter (default null) is completely unaddressed, leaving the agent to infer its purpose from the schema name alone.

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 states a specific resource, 'the gesture map in force in VR for this scene', and enumerates what each row contains (intent, shape, hand, hold time, read location, ownership, collisions, ignored values). It distinguishes itself from stage_gesture_set and stage_gesture_reset by naming them as the rebind and reset alternatives. The one weakness is that it never uses a clear verb like 'show/list', leaving the read operation implied by 'in force'.

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?

It explicitly routes rebinding to stage_gesture_set and default restoration to stage_gesture_reset, which gives the agent clear alternatives. It does not state the positive case ('use this to inspect current bindings') or any prerequisites, but the intended usage is strongly implied by the contrast with the mutation siblings.

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