Stage Keys Set

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

With no annotations, the description carries the full burden and largely meets it: it discloses atomicity ('Every key is checked before any is written'), overwrite semantics ('A key at the same t replaces the old one'), destructive scope of `replace` ('objects whose old keys go first'), and a side effect on the stage clock ('the clock's span grows to take keys past its end'). It stops short of describing failure behavior, permissions, or what invalid keys return.

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?

Information-dense and front-loaded with the purpose, but written as a single run-on paragraph of telegraphic fragments and parentheticals ('(cameras and lights; stored as a quaternion, so renders read it as any key)'). It earns most of its length yet sacrifices scannability.

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 still sketches the reply ('Page replies {keyed, keys (per object, its key count), span}') and the 'Emits: keyed' event, which is extra useful context. Combined with the atomicity and clock-growth notes, the definition is nearly complete for a 5-param mutation tool; only the undocumented `scene` param and error behavior 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 coverage is 0%, so the description must compensate and it substantially does: it spells out the `keys` item shape (name, t, location, look, quaternion, world units, seconds) plus defaults for omitted channels, and explains `replace`, `interp`, and `save` semantics. The required `scene` parameter is never mentioned anywhere, leaving one of five params undocumented.

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?

Opens with a specific verb and scope: 'Many keys in one call, from values, on any objects', which distinguishes it from the singular stage_key_set sibling via the 'many vs one' framing and the '(page command: key with keys)' mapping. The purpose is recoverable but expressed in dense domain shorthand that an unfamiliar agent must decode.

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 routes the agent to related tools explicitly: 'interp: ... (stage_key_interp)', 'save=True also saves anim.json (stage_anim_save)', and 'replace: objects whose old keys go first'. The remaining gap is that nothing states when to prefer this over the singular stage_key_set rather than merely implying it via 'many keys in one call'.

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