fal.ai MCP Server

Overview Schema Source Related Servers Discussions Admin

Update asset character

update_asset_character

Destructive

Update a character in your fal Assets library by setting its name, description, cover image, or reference images. Use asset IDs or request IDs for existing fal-generated images.

Instructions

Update an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.

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": {
      "character_id": "<character_id>"
    },
    "name": "update_asset_character"
  }
}

Input Schema

Name	Required	Description
`name`	No	Character display name
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`description`	No	Text description used for character semantic matching
`character_id`	Yes	Character collection ID
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`Idempotency_Key`	No	Optional idempotency key for safe request retries
`cover_image_url`	No	Optional fal-hosted cover image URL for the character
`reference_images`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv3.0.1Oct 5, 2026

addedInput schema / $defs

Added value: +{
+  "reference_images": {
+    "description": "Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images.",
+    "items": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "maxItems": 20,
+    "minItems": 1,
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / reference_images / $ref
```
Added value: +"#/$defs/reference_images"
```

removedInput schema / properties / payload / properties / reference_images / description

Removed value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."

removedInput schema / properties / payload / properties / reference_images / items
```
Removed value: -{
-  "minLength": 1,
-  "type": "string"
-}
```
removedInput schema / properties / payload / properties / reference_images / maxItems
```
Removed value: -20
```
removedInput schema / properties / payload / properties / reference_images / minItems
```
Removed value: -1
```
removedInput schema / properties / payload / properties / reference_images / type
```
Removed value: -"array"
```
addedInput schema / properties / reference_images / $ref
```
Added value: +"#/$defs/reference_images"
```

removedInput schema / properties / reference_images / description

Removed value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."

removedInput schema / properties / reference_images / items

Removed value: -{
-  "minLength": 1,
-  "type": "string"
-}

removedInput schema / properties / reference_images / maxItems
```
Removed value: -20
```
removedInput schema / properties / reference_images / minItems
```
Removed value: -1
```
removedInput schema / properties / reference_images / type
```
Removed value: -"array"
```

First observedv2.0.0Oct 3, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered. The description adds one useful behavioral note (unresolved ID references are materialized before character state is added) but is silent on partial-update semantics, the confirm flag's role, and idempotency-key behavior, leaving notable mutation behavior unexplained.

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?

Three tight sentences with the purpose front-loaded and no filler. The reference-images clause is dense but earns its place given the ambiguity between IDs and URLs.

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

Completeness3/5

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

For a 10-parameter, destructive mutation with nested objects and no output schema, the description covers purpose and reference-image semantics but omits the confirm flag, idempotency usage, and the exclusivity between payload, payload_file, and flat flags. The rich schema compensates, but the description is only minimally complete.

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 description coverage is 90%, so the schema already documents nearly every parameter, and the description's reference_images sentence is essentially duplicated verbatim from the schema. No additional meaning is added for character_id, confirm, account, payload, or the flat-vs-payload mutual exclusion; baseline 3 applies.

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

Purpose4/5

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

States a specific verb (Update) and resource (asset character) within the fal Assets library, which cleanly separates it from create_asset_character and delete_asset_character. It does not name those siblings explicitly, so an agent must infer the boundary from the verb alone.

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

Usage Guidelines3/5

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

The description gives real guidance for one parameter family (prefer vector/request IDs over URLs for reference_images), which is genuine when-to-use advice. However, it offers no guidance on when to update versus creating a new character, no prerequisites, and no mention of the mutually exclusive body forms.

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

Deploy Server