Adds a shape key (morph target) to a mesh object. Automatically creates a Basis key if none exists, and can create from the current mesh state.
Add a shape key (morph target) to a mesh object.
Automatically creates the Basis key if none exists.
Args: object_name: Target mesh object. name: Name for the new shape key. from_mix: Create from current mesh state.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Key | |
| from_mix | No | ||
| object_name | Yes |
Changes observed during successful MCP inspections.
v3.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the auto-creation of the Basis key and the 'from_mix' behavior, which adds useful context. However, it doesn't mention error handling (e.g., invalid object type), behavior if the name already exists, or return values. Partial coverage.
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 concise: two sentences plus a compact argument list. Purpose is front-loaded and there is no fluff. It could be improved by structuring the parameter explanations more formally, but it is efficient and easy to parse.
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 output schema and no annotations, the description covers the core purpose, parameters, and a key behavior (auto-creating Basis). It lacks explicit error handling, interaction with existing keys, and confirmation of mutation. For a straightforward add operation, it is mostly complete but not exhaustive.
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 explain parameters. It does: object_name is 'Target mesh object', name is 'Name for the new shape key', from_mix is 'Create from current mesh state'. This adds meaning beyond the schema's types and defaults, though it could be slightly more detailed (e.g., what 'from current mesh state' implies).
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 clearly states the action: 'Add a shape key (morph target) to a mesh object.' It specifies the resource (mesh object) and the auto-creation of Basis key. While it doesn't explicitly contrast with sibling tools like set_shape_key_value or remove_shape_key, the verb and resource are specific and unambiguous.
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?
No guidance on when to use this tool versus alternatives. It doesn't mention that this is for creating new keys while others are for setting or removing, nor does it describe any prerequisites or context. The description simply states the function without differentiating usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.