Skip to main content
Glama

add_shape_key

Create a shape key (blend shape) on a mesh to store alternative vertex positions blended by a 0-1 value for expressions, morphs, or corrective shapes; first call creates the Basis.

Instructions

Add a shape key (blend shape). The first call also creates the Basis.

Shape keys store alternative vertex positions blended by a 0-1 value: facial expressions, morphs, corrective shapes. Shape it with move_shape_key_vertices, blend with set_shape_key, animate with keyframe_shape_key. A new key starts at value 1.0 (fully on), so edits show straight away; set it to 0 to hide it.

Args: object_name: Mesh object. key_name: Name for the new shape key. from_mix: Start from the current blend of all keys instead of the Basis.

Returns: Dict with the new key and every key on the object.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "object_name": "<object_name>",
      "key_name": "<key_name>"
    },
    "name": "add_shape_key"
  }
}

Input Schema

NameRequiredDescriptionDefault
from_mixNo
key_nameYes
object_nameYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv3.0.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the first invocation implicitly creates the Basis key, new keys start at value 1.0 (fully on) so edits are immediately visible, and the return value is a dict of the new key plus all keys. It does not mention any permission or failure conditions, but for an additive creation call that is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action and the Basis side effect, then the workflow context, then the startup-value behavior, then a compact Args block. Every sentence carries information an agent needs before calling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Parameter docs compensate for the 0% schema coverage, and the output shape is briefly noted even though an output schema exists. Given no annotations, the description covers the essentials an agent needs to create and then use a shape key, with only the exact object-identifier semantics left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must document all three params, and it does: object_name as the mesh object, key_name as the name for the new key, and from_mix as starting from the current blend instead of the Basis. The from_mix explanation adds real meaning beyond the bare field name, though object_name stays vague about whether it accepts the active object or requires an exact name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a shape key (blend shape)') and adds the key non-obvious fact that the first call also creates the Basis. This distinguishes it clearly from siblings like set_shape_key, move_shape_key_vertices, and keyframe_shape_key, which are named as separate workflow steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to the complementary tools: 'Shape it with move_shape_key_vertices, blend with set_shape_key, animate with keyframe_shape_key', so the agent knows this tool is the creation step in a sequence. It also gives practical guidance on the starting value (1.0) and how to hide the key (set to 0). No explicit when-not-to-use case, keeping it short of a 5.

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

Deploy Server

Other Tools