Stage Performance

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

With no annotations, the description carries the full burden, and it does disclose real behavioral detail: the default-to-newest selection, the mapping from kept takes to performance data (meta: performance, perf_shift), and the on-disk layout. However, it never states that the tool is a read-only operation, what happens if the requested perf is absent, or whether missing clip files are an error.

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 one long, jargon-dense sentence block where file paths and clock-snapping detail occupy as much space as the tool's actual action. Nothing is truly wasted, but the essential 'returns the performance for a scene' point is not front-loaded.

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, yet the description spends most of its length describing returned content rather than the call semantics. For a two-parameter lookup embedded in a very large stage toolset, it should clarify selection rules, failure modes, and its relationship to stage_perform and stage_takes; those gaps remain.

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%, so the description must compensate, and it partially does: the perf parameter's default behavior (newest when omitted) is spelled out, and the scene parameter's meaning is implied by the <scenes>/<scene>/performances/... path. It never says whether perf is a directory name, an ID, or a title, which leaves the required parameter underspecified.

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 explains what a performance record contains and implies retrieval by saying it is 'a performance as text (the newest when perf= is not given)', but the operative verb (read/fetch) is never stated. Against a large sibling set including stage_perform, stage_takes, and stage_take_transcribe, nothing distinguishes this as the retrieval of an existing performance rather than its creation or playback.

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?

There is no explicit guidance on when to call this versus alternatives such as stage_takes or stage_perform. The only contextual cue is the implicit default ('the newest when perf= is not given'), which hints at behavior but does not tell the agent what situation selects this tool.

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