Skip to main content
Glama

act

Direct cast performances in a shot by adding, changing, removing, or clearing timed actions, emotions, talk, and looks with precise percentage timing.

Instructions

Direct the cast of a shot. kind action: a move (type from library actions) by actor, some need a target; timed by when or exact at %. kind emotion: a face feeling on member at %. kind talk: member's mouth moves from % to %. kind look: member looks at target from % to %. op add (default), change (id), remove (id), clear (all of that kind). Ids must come from the current style: call library to see them (a wrong id is refused with the valid list). Returns the item id. One undo step for the person. To place or remove people use cast; for exact paths over time use keys.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "act"
  }
}

Input Schema

NameRequiredDescriptionDefault
atNoWhen it happens, in % through the shot (0 to 100)
idNoThe action/emotion/talk/look id, for change and remove.
opNoadd if left out. clear removes every item of this kind in the shot.
toNoEnd, in % through the shot (0 to 100)
fromNoStart, in % through the shot (0 to 100)
kindNoaction if left out.
shotNoThe shot's id (from get_project). Left out: the shot on screen.
sideNoFor sided moves.
typeNoAction id (library actions).
whenNoRough timing in the shot. Use at for an exact %.
actorNoMember id or name doing the action (first cast member if left out).
speedNoAction speed, 1 is normal.
memberNoFor emotion, talk, look: whose face.
targetNoMember id or name it's done to / looked at.
emotionNoEmotion id (library emotions).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.2
    • changedInput schema / properties / emotion / description
      Previous value: -"Emotion id."New value: +"Emotion id (library emotions)."
    • addedInput schema / properties / op / description
      Added value: +"add if left out. clear removes every item of this kind in the shot."
    • changedInput schema / properties / type / description
      Previous value: -"Action id."New value: +"Action id (library actions)."
    • addedInput schema / properties / when / description
      Added value: +"Rough timing in the shot. Use at for an exact %."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations only declare it is not read-only, not idempotent, and not destructive; the description adds real behavior: a wrong id is refused with the valid list, it returns the item id, and it collapses into one undo step. It does not discuss permissions or what 'clear' irreversibly wipes beyond the schema's own note.

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

Conciseness4/5

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

Purpose and sibling routing are front-loaded, and the kind-by-kind breakdown is compact with no filler. The telegraphic, run-on phrasing ('a face feeling on member at %') costs some readability but nothing is redundant.

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?

For a 15-parameter mutation tool with no output schema, the description covers the kind/param relationships, op semantics, id sourcing, return value, and undo behavior. Remaining gaps are minor details like speed and side handling, which the schema already describes.

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

Parameters3/5

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

Schema coverage is 100%, so per-parameter meaning is already documented and the baseline is 3. The description does add cross-parameter mapping (which of actor/target/member/from/to apply to each kind), but it stays terse and does not clarify speed, side, or how id interacts with change versus remove.

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 ('Direct the cast of a shot') and then enumerates the four kinds of direction it accepts (action, emotion, talk, look). It explicitly separates itself from siblings cast and keys, so an agent can route correctly without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: 'To place or remove people use cast; for exact paths over time use keys,' and instructs to call library for valid ids. It also states the wrong-id failure mode, which tells the agent what to do on error.

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