fgui_add_keyframes

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

With no annotations supplied, the description carries the full behavioral burden and does substantial work: it discloses atomic undo/redo, all-or-nothing rejection when the same track and frame already exist (no partial writes), value sampling from current object state, and the save plus disk-XML verification path. It does not describe failure modes beyond duplicate rejection or how the operation interacts with an unsaved document, which keeps it below a 5.

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 purpose and atomicity guarantee are front-loaded, and each subsequent line adds distinct information (field requirements, duplicate rejection, save/verify behavior) with no filler. The final line is dense and would read better if it named the verify parameter explicitly, but nothing is redundant.

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 return values need not be described, and the description covers the key behavioral risks: atomic rollback, duplicate rejection, state sampling, and save-time verification. The remaining gap is the unexplained name parameter and the missing disambiguation against fgui_set_keyframe, both of which matter for a 5-parameter mutation tool.

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 does explain the KeyframeSpec fields (targetId with empty meaning root component, type, frame, value omission, label) plus save and external_reload with the save=True dependency. However, the required top-level parameter name is never explained, and verify is only obliquely alluded to as 'default comparison' without being named as a parameter.

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 gives a specific verb plus resource: creating keyframes on a Transition timeline, with the scope of one atomic call. It distinguishes itself from generic transition-item tools by naming the Transition timeline and keyframe mechanics, but it never mentions the closely related sibling fgui_set_keyframe, so the boundary between the two is left for the agent to infer.

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 implied through the Transition timeline context and the note that value is sampled from the object's current state when omitted, which tells the agent this is an authoring-time write. There is no explicit when-to-use versus fgui_set_keyframe, fgui_add_transition_item, or fgui_update_transition_item, and no stated prerequisites such as an open document or active branch.

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