Skip to main content
Glama

openFlow

by io.github.molkex
OverviewDiscussionsAdmin

generate_character_image

Generate a portrait or body image for an existing Flow character.

entity_id: the character's entityId — from create_character or
create_character_from_photo, or create_character_from_description's own result
(which already calls this for slot 0 — no need to call it again for that slot).
character_slot_index: 0 for portrait, 1 for body. Flow keeps the two slots
visually consistent server-side once they share an entityId — no reference
image needed for the body shot.

ONE-SHOT PER SLOT, confirmed live 2026-07-25: each slot can be written exactly
once — a second generate_character_image call into an ALREADY-FILLED slot fails
(HTTP 500), it does not overwrite. Also confirmed: the FIRST write into a slot
500s on a card with no personality_notes saved yet — call update_character with
personality_notes before the first generate_character_image on a fresh entity_id.
If you're using create_character_from_description, both of these are already
handled for slot 0; this caveat mainly matters if you're driving slot 1 (body) or
entity_id yourself.

THIS TOOL DOES NOT PLACE A CHARACTER INTO A NEW SCENE — it only ever (re)writes
the character's own portrait/body slot, once. For "generate a picture of this
character doing X", use generate_with_face(character=..., prompt=...) instead,
which conditions on the reference image, not entity_id.

CAVEAT confirmed live 2026-07-11: for a character seeded from a REAL PHOTO
(create_character_from_photo), this text-prompt generation is NOT reliable for
identity — it conditions on a text description, not the real photo's pixels, and
was confirmed to drift to an unrelated-looking person even with a detailed
physical description saved on the entity. Fine for invented/stylized characters.
If the goal is "content that looks like a real person," use
generate_video_with_reference (r2v) instead — see its docstring.

Only works for the account whose project actually owns this entity_id —
characters are per-account, same as projects. Pass that account as `account`
(optional for a character saved in list_characters(): it is looked up).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modelNoNARWHAL
aspectNoIMAGE_ASPECT_RATIO_LANDSCAPE
promptYes
accountNo
entity_idYes
character_slot_indexYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / account
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Account"
+}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnly=false/idempotent=false/destructive=false/openWorld=true; the description goes far beyond by disclosing the one-shot-per-slot write semantics (second call 500s and does not overwrite), the personality_notes precondition, and the identity-drift failure mode for real-photo entities. These are exactly the operational traits annotations cannot convey.

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 is front-loaded and every paragraph carries a distinct, actionable caveat rather than filler. It is nonetheless long and dense, with dated provenance tags ('confirmed live 2026-07-25') that add ceremony more than decision-relevant signal.

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?

For a mutation tool with no output schema and high failure complexity, the description covers ownership scoping, write-once semantics, prerequisites, and the correct alternative tools. Nothing an agent needs to invoke this safely and correctly is missing.

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?

With 0% schema description coverage the description must carry the load. It defines the two genuinely ambiguous parameters well (entity_id provenance, character_slot_index = 0 portrait / 1 body) plus account scoping, but says nothing about prompt content, model choice, or aspect beyond what the enums self-describe.

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 up front: 'Generate a portrait or body image for an existing Flow character.' It explicitly distinguishes itself from the two nearest siblings (generate_with_face and create_character_from_description) within the text, so an agent can route correctly without opening any 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 when/when-not and named alternatives: use generate_with_face for 'character doing X', use generate_video_with_reference for real-photo identity content, and do not re-call for slot 0 after create_character_from_description. It also states the sequencing prerequisite (update_character with personality_notes before the first write).

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

All openFlow toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources