set_keyframe

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Insert keyframes') but does not disclose whether existing keyframes are overwritten, whether the operation is destructive, whether it requires the object to be animated or have an action assigned, or what happens when property_name is empty. For a mutation tool with zero annotation coverage, this is a significant gap.

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 description is compact and front-loaded with the main action, followed by a parameter list. However, the parameter list is redundant with the input schema (which already provides names, types, and defaults), and the one-line parameter explanations are terse to the point of being ambiguous. It is not bloated, but it does not earn full credit for structure because it leans on a schema that lacks descriptions.

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?

For a 6-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is incomplete. It does not explain the boolean flag semantics, the meaning of an empty property_name, the relationship between frame=None and the current frame, or the effect of setting multiple flags at once. An agent would likely need to guess or experiment to call this tool correctly.

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. It lists parameter names and one-line meanings ('Frame number (None = current frame)', 'Keyframe location'), but it does not explain the boolean semantics of location/rotation/scale (e.g., whether true means 'insert a keyframe for this channel'), nor how property_name interacts with the other flags. The description adds minimal value beyond the schema's property names and defaults.

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 verb and resource: 'Insert keyframes for an object.' It clearly identifies the action (inserting keyframes) and the target (an object), and the parameter list enumerates what can be keyframed (location, rotation, scale, custom property). It is distinguishable from siblings like delete_keyframe and set_interpolation, though it does not explicitly name them.

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?

The description implies usage context: it is for inserting keyframes on an object, and the parameter list indicates which transform channels can be keyframed. However, it does not explicitly state when to use this tool versus alternatives like set_interpolation, go_to_frame, or set_animation_range, nor does it mention prerequisites such as the object needing to exist or be selected.

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