add_keyframe

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

No annotations provided, so description must carry full burden. It discloses that values are set before keying and rotation values are auto-converted from degrees. However, it does not state whether existing keyframes at the same frame are overwritten, what happens if the property is not animatable, or any error conditions.

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?

Concise with purpose sentence followed by parameter list. No redundant text. Front-loaded purpose. Bullet list is clear, though could be slightly more compact.

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?

Given no annotations or output schema, the description covers parameter semantics but lacks important behavioral context: return value, error handling, effect on existing animation data. Adequate for basic use but incomplete for a tool that modifies animation state.

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 has 0% description coverage, so the description adds substantial meaning. Each parameter is explained with examples: data_path lists common values, frame notes default, value explains comma-separated format and degree conversion. Could be more precise about coordinate ordering (e.g., 'location' is XYZ), but overall strong.

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?

Clearly states the tool inserts an animation keyframe on an object property. The verb 'insert' and resource 'keyframe on object property' are specific. It distinguishes from sibling tools like move_object and rotate_object that directly modify transforms without keyframing.

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?

Implied usage through parameter descriptions but no explicit guidance on when to use this tool vs alternatives like direct property manipulation. No 'when not to use' or comparison to similar tools like set_vertex_position.

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