Skip to main content
Glama

Suggest graphics for a scene

suggest_graphics

Proposes up to max (default 3) motion graphics for one scene of a long-form project, from its script and its take's transcript: each with its template, data (every figure from the script), placement, the words it starts and ends on, its start and end in seconds in the finished video, and why. Nothing is saved: each proposal's add_with is the add_graphic arguments that add it as it is; dropped says what was left out and why. 2 credits a call: use estimate_only first and tell the person the price. model is any gateway "provider/model" (default google/gemini-2.5-flash-lite).

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": {
      "project_id": "<project_id>",
      "scene_id": "<scene_id>"
    },
    "name": "suggest_graphics"
  }
}

Input Schema

NameRequiredDescriptionDefault
maxNoAt most how many graphics to propose, 1 to 5; default 3
modelNoGateway "provider/model" id; default google/gemini-2.5-flash-lite, the cheapest that passed the eval
scene_idYesThe scene to suggest graphics for (get_project lists them); its selected take needs a transcript
project_idYesFrom create_project
estimate_onlyNoPrice it without spending; tell the person the price first

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag a non-read-only, open-world, non-idempotent call, and the description adds what they cannot: "Nothing is saved," a cost of "2 credits a call," the requirement that the scene's selected take have a transcript, and the meaning of the dropped field. That is exactly the behavioral context an agent needs before spending credits.

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?

Front-loaded with purpose and scope, then cost and model defaults, with no filler sentences. The enumeration of returned fields makes one long run-on clause, which slightly hurts scanability but every element carries information.

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

Completeness5/5

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

There is no output schema, and the description fully covers the return shape: template, data, placement, start/end words, start/end seconds, rationale, plus add_with and dropped. Combined with the credit cost and transcript prerequisite, an agent has everything needed to call it correctly.

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 all five parameters are already documented, including max bounds, the model pattern, and the transcript prerequisite. The description only restates the defaults for max and model and the pricing purpose of estimate_only, adding little semantic meaning beyond the schema.

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 with scope: "Proposes up to max (default 3) motion graphics for one scene of a long-form project, from its script and its take's transcript." It also separates itself from the sibling add_graphic by explaining that nothing is saved and that add_with is the argument set for adding a proposal.

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?

Gives concrete workflow guidance: "use estimate_only first and tell the person the price," and implies the add_graphic handoff via add_with. It does not explicitly say when to prefer this over other suggestion tools such as suggest_regions or suggest_shorts, so it falls short of full when/when-not coverage.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources