How do I use fal.ai MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fal.ai MCP Server find the latest fal.ai image model and show its pricing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

fal.ai MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

fal.ai MCP Server & CLI

npm License YouTube LinkedIn

fal.ai MCP server and CLI for Codex and AI agents. 66 shared tools for current models, queue receipts, Assets and storage controls, private account profiles and exact reviewed generation batches.

One package provides a task CLI, local stdio MCP and versioned desktop bundle. Built and maintained by Navid Moazzez. Complete setup: navid.me.

The terminal illustrates actual commands, not a recorded provider account session. Node 22+ is required for manual installs; private account access, model eligibility and generation credits remain separate.

Two ways to use it

Command line

A terminal or shell agent calls only the requested task.

npx -y --package @thenavidm/fal-ai-mcp-cli@latest fal-ai-cli search-models --limit 1 --agent

MCP server, for your AI app

codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latest

Which one

Use the CLI for task-specific shell discovery/compact selected output, or MCP for an AI client supporting local tools. Both enforce the same handlers, validation and approval policy.

Related MCP server: fal.ai MCP Server

Features

Current dynamic model/schema discovery, receipt-based queue operations and full native creative platform arguments.
Shared local confirmation/read-only policy and isolated account API keys.
Exact current-schema/unit-quote batch review and stop-on-failure receipts.
Native Assets, collection, tag, character and CDN ACL/retention controls.
Complete Codex/client/OS/desktop setup, current comparisons, version history and accordion FAQs.

Section	What it covers
1. What you can ask it	What you can ask it
2. Quick install	Quick install
3. Set up fal.ai access	Set up fal.ai access
4. Connect your client	Connect your client
5. Check it works	Check it works
6. Output, flags and exit codes	Output, flags and exit codes
7. MCP or CLI and token cost	MCP or CLI and token cost
8. Every tool and argument	Every tool and argument
9. Model and asset workflows	Model and asset workflows
10. Exact reviewed batches and pagination	Exact reviewed batches and pagination
11. Several private accounts	Several private accounts
12. Writing safely	Writing safely
13. How the two surfaces work	How the two surfaces work
14. Your data	Your data
15. Environment variables	Environment variables
16. Updates and removal	Updates and removal
17. Troubleshooting	Troubleshooting
18. API coverage and comparisons	API coverage and comparisons
19. Versions and migration	Versions and migration
20. FAQ	FAQ

1. What you can ask it

Find exact current image, video, audio or 3D endpoint IDs and inspect their native schemas.
Read unit pricing, estimate quantities deliberately and inspect the intended account's billable usage.
Submit only the approved native model payload, keep its request ID and read progress/results once.
Review several ordered generations against current schemas and prices, then submit only that matching approved batch.
Browse and manage requested Assets, collections, tags and characters using native fields.
Read or explicitly change CDN ACL/retention settings and save a signed access URL privately.

Actual shared discovery exposes 66 tools: 32 reads and 34 confirmed operations. It wraps 53 selected current native platform operations plus 13 creative/account/batch helpers. All nine legacy tool names remain, with deliberate 2.0 breaking argument/behavior corrections documented below. Generic model support is conditional on discoverable/compilable current JSON schemas, credentials and model access; it is not a guarantee that every current/future endpoint works.

2. Quick install

npm install -g @thenavidm/fal-ai-mcp-cli@latest
fal-ai-cli --version
fal-ai-cli tools
fal-ai-cli schema submit-job
fal-ai-cli login

Node 22+ for manual CLI/local MCP. INSTALL.md covers every declared client/OS and the versioned desktop bundle. Official genmedia and Python fal are separate binaries; ours is fal-ai-cli.

3. Set up fal.ai access

Private account access

Sign into the intended fal account. Confirm which personal/team account owns the credits and key before creating or copying it.
Use only the provider permissions needed for the requested work. Model execution, Assets, billing and organization reads have different requirements. A working model read does not prove asset/admin permissions.
Store FAL_KEY in private user/client environment settings or FAL_TOKEN_FILE as an absolute token-only file outside Git. On macOS/Linux use an owner-private directory and regular non-symlink 0600 file, at most 64 KiB. On Windows restrict ACLs to yourself; POSIX mode does not prove Windows ACLs.
Run fal-ai-cli doctor for local settings; doctor --network deliberately reads one model with limit=1. It reports count only, does not spend credits and does not prove the authenticated owner. Public model discovery can work without a key.
Inspect the exact current model schema and unit pricing before approving generation. Use a queue receipt to read progress/results; never submit again to check progress. Do not generate paid media, create keys or delete assets just to test installation.

FAL_ACCOUNTS is a private JSON array of unique {name,api_key,token_file} profiles; FAL_DEFAULT_ACCOUNT selects an exact label. A selected token file overrides only that profile's key. Explicit profiles never inherit FAL_KEY or another profile after missing credentials or a 401/403. Labels are not verified fal owners. Tokens cache until process restart; rotate/revoke at fal and restart clients.

This wrapper uses API keys with Authorization: Key on fixed api.fal.ai, queue.fal.run, fal.run and the SDK-pinned rest.fal.ai upload-initiation origin. No credential goes on the CDN upload PUT. No hosted OAuth, .env loading, SDK key-ID/secret environment inheritance, official genmedia config import, session cookie import, telemetry or automatic background update exists. login prints setup instructions and does not save credentials or start sign-in.

Official account connections

The current model-generation MCP uses OAuth at https://mcp.fal.ai/mcp-relay. Its Active MCP account setting routes new uploads/generations; old jobs remain with their original account, and failed selected-account access does not fall back to personal credits. This is already an official isolation feature. API-key clients, including this package and genmedia, use the key's owning account separately.

The separate Platform MCP at https://api.fal.ai/v1/mcp/platform uses API keys and is read-only account/serverless tooling. Documentation MCP at https://fal.ai/docs/mcp searches public docs without model execution. The old March launch article/key-based endpoint and its nine tools are historical evidence, not the current OAuth setup or tool count.

Costs and permissions

The AGPL wrapper is free; fal generation credits, endpoint pricing, output quantities, model eligibility and concurrency limits apply. Unit pricing and cost estimates are different from completed billable usage. Unit quotes can scale with resolution, duration, output count or GPU time; a batch of ten requests is not a ten-output or ten-dollar limit. No local budget guarantee or credit reservation is promised.

No requests automatically retry, including reads, 429, failed uploads, timeouts or 5xx. Respect current provider throttling guidance before deliberately repeating a read. A timeout after a paid POST may have spent credits without returning a request ID: inspect fal history before another submission. Responses cap at 5 MiB and JSON requests at 1 MiB. One native list page is returned with its real cursor; there is no invented all-pages backup.

Data and file controls

Generated and uploaded CDN media may be public under account defaults. The local generation default sends X-Fal-Store-IO:0 to disable provider JSON input/output storage; CDN media access and expiration are separate. Explicit store_io:true allows native payload storage. Native lifecycle JSON can specify expiration_duration_seconds and initial_acl with default allow/forbid/hide and nickname rules. Unknown nicknames may be silently dropped by fal; an ACL request is not proof of actual external visibility.

Local upload sends only the selected regular file, 1 byte–20 MiB, through upload initiation and one restricted fal.media PUT. Larger/multipart/remote-URL upload conveniences belong to the official clients; no retry or automatic generation occurs here. Sign-file URL credentials are saved only into an exclusive new private JSON file. Existing files are never overwritten. Keep parent directory and Windows ACLs private; a signature is access authority even if its field says URL.

Rotation and revocation

Revoke the exact key at fal, replace private settings/files and restart every process. Revoke official OAuth connections separately. Removing the package/client registration does not cancel jobs, undo asset mutations, delete provider payloads/CDN files, revoke credentials or refund generation credits. Inspect receipts and provider state before explicitly requested cleanup.

4. Connect your client

Codex setup comes first in INSTALL.md, followed by Claude Code, Claude Desktop extension/manual stdio, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other local stdio clients on macOS/Windows/Linux. Use private key settings available to the actual local/remote runtime. GUI apps may not inherit terminal environment; restart after changing settings.

This package provides local stdio. Remote-only clients use the provider-hosted OAuth relay. Skills are optional agent guidance; installing npm does not register SKILL.md automatically. No Claude Code installation is needed for Codex.

codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latest

5. Check it works

fal-ai-cli --version
fal-ai-cli tools
fal-ai-cli list-accounts --agent
fal-ai-cli doctor
fal-ai-cli doctor --network
fal-ai-cli search-models --limit 1 --agent
fal-ai-cli get-model-info --model-id fal-ai/flux/dev --agent

Public model discovery/schema reads have been verified without credentials or generation credits. Private doctor --network reads one model with count only; model metadata can be public, so that result is not an account-owner or all-permissions test. Model runs, authenticated Assets and real queue outcomes require separate live-account verification. Never use a paid or destructive call as an install smoke test.

6. Output, flags and exit codes

Both surfaces return provider JSON through the same handlers. Queue submission returns request_id receipts with completed:false. get_job_status and get_job_result read once; cancel receipts do not prove stopped processing/refunds. Synchronous run timeouts can leave an unknown paid outcome. No returned media is downloaded or embedded automatically. Signed access credentials go only to a new exclusive private file; console responses contain saved-file metadata.

Use the actual task schema. Repeated primitive array flags pass one value each; repeated --tasks values are individual JSON task objects. Complete native body unions use --payload JSON or a private --payload-file, mutually exclusive with flat body flags. Native query/header/body names remain visible in the schema; kebab-case flags come from the shared house bridge.

fal-ai-cli search-models --limit 5 --agent --select models,next_cursor
fal-ai-cli submit-job --help
fal-ai-cli schema estimate-pricing

Flag	Behavior
--agent	Compact JSON, no input/color; never confirmation
--confirm	Explicit approval for exactly the requested operation
--account LABEL	Exact private API-key profile
--select a,b.c	Local output field selection
--payload / --payload-file	Native body, mutually exclusive with other body routes
--tasks JSON	Repeat an individual ordered generation object
--review-sha256 HASH	Exact preview hash before batch submission
--output-file PATH	New private signed-URL credential file

Exit	Meaning
0	Handler success/receipt; submission does not mean completed generation
2	Invalid input or refused policy operation
3	Not found
4	Provider authentication/permissions
5	Provider/network/unknown outcome
7	Rate limit
10	Missing or invalid local account credentials/configuration

7. MCP or CLI and token cost

The tools, schemas, handlers and write guard are shared. MCP clients discover local tools; shell agents can inspect command help/schema only when needed and select smaller result fields. Context cost depends on client tool discovery, loaded descriptions/schemas, prompts and output size.

No fresh matched successful Codex task/token comparison is measured for this release. Tool-list bytes or characters divided by four are not API usage. Actual schemas/receipts and refusal fixtures establish local behavior, not cost efficiency or universal superiority. Measure the same successful task and result coverage in the intended client before publishing a saving percentage. Historical Claude numbers from other packages do not apply here.

8. Every tool and argument

`search_models`

Unified endpoint for discovering model endpoints. Supports three usage modes: 1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata. 2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs. 3. Search Mode (search parameters): Filter models by free-text query, category, or status. Expansion: Use expand to include additional data in each model object: - openapi-3.0 : full OpenAPI 3.0 schema in the openapi field - enterprise_status : enterprise readiness status (ready or pending) in the enterprise_status field Examples of endpoint_id values: - fal-ai/flux/dev - fal-ai/wan/v2.2-a14b/text-to-video - fal-ai/minimax/video-01/image-to-video - fal-ai/hunyuan3d-v21 See fal.ai Model APIs for more details. Authentication: Optional. Providing an API key grants higher rate limits. Common Use Cases: - Browse available models for integration - Retrieve metadata for specific endpoints - Search for models by category or keywords - Get OpenAPI schemas for code generation - Build model selection interfaces

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`endpoint_id`	No; body/guard requirements still apply	JSON	Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2
`q`	No; body/guard requirements still apply	string	Free-text search query to filter models by name, description, or category
`category`	No; body/guard requirements still apply	string	Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
`status`	No; body/guard requirements still apply	string	Filter models by status - omit to include all statuses enum: `["active", "deprecated"]`.
`expand`	No; body/guard requirements still apply	JSON	Fields to expand in the response. Supported values: 'openapi-3.0' (includes full OpenAPI 3.0 schema in 'openapi' field), 'enterprise_status' (includes enterprise readiness status)
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_pricing`

Returns unit pricing for requested endpoint IDs. Most models use output-based pricing (e.g., per image/video with proportional adjustments for resolution/length). Some models use GPU-based pricing depending on architecture. Values are expressed per model's billing unit in a given currency. Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Display pricing in user interfaces - Compare pricing across different models - Build cost estimation tools - Check current billing rates See fal.ai pricing for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`endpoint_id`	Yes	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

`estimate_pricing`

Computes cost estimates using one of two methods: 1. Historical API Price (historical_api_price): - Based on historical pricing per API call from past usage patterns - Takes call_quantity (number of API calls) per endpoint - Useful for estimating based on actual historical usage patterns - Example: "How much will 100 calls to flux/dev cost?" 2. Unit Price (unit_price): - Based on unit price × expected billing units from pricing service - Takes unit_quantity (number of billing units like images/videos) per endpoint - Useful when you know the expected output quantity - Example: "How much will 50 images from flux/dev cost?" Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Pre-calculate costs for batch operations - Display cost estimates in user interfaces - Budget planning and cost optimization See fal.ai pricing for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`payload`	No; body/guard requirements still apply	JSON	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

input.payload oneOf branch 1

Argument	Required	Type	Details
`estimate_type`	Yes	string	Estimate type: historical API pricing based on past usage patterns enum: `["historical_api_price"]`.
`endpoints`	Yes	object	Map of endpoint IDs to call quantities

input.payload.oneOf1.endpoints

input.payload.oneOf1.endpoints.{key}

Argument	Required	Type	Details
`call_quantity`	Yes	integer	Number of API calls to estimate (regardless of units per call) minimum: `1`.

input.payload oneOf branch 2

Argument	Required	Type	Details
`estimate_type`	Yes	string	Estimate type: unit price calculation based on billing units enum: `["unit_price"]`.
`endpoints`	Yes	object	Map of endpoint IDs to unit quantities

input.payload.oneOf2.endpoints

input.payload.oneOf2.endpoints.{key}

Argument	Required	Type	Details
`unit_quantity`	Yes	number	Number of billing units expected (e.g., number of images, videos, etc.) minimum: `1e-06`.

`get_usage`

Returns paginated usage records for your workspace with filters for endpoint, user, date range, and auth method. Each item includes the billed unit quantity, the pre-discount unit price and cost_subtotal, any percentage discount applied, and the final cost_total (cost_subtotal − cost_discount). Key Features: - Usage data for all endpoints or filtered by specific endpoint(s) - Flexible date range filtering - User-specific usage tracking - Detailed usage line items with unit quantity, price, and discount breakdown - Paginated results for large datasets Common Use Cases: - Generate usage reports for all endpoints or specific models - Track usage patterns - Monitor endpoint usage across different auth methods - Build usage dashboards and visualizations See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`start`	No; body/guard requirements still apply	JSON	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`end`	No; body/guard requirements still apply	JSON	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`timezone`	No; body/guard requirements still apply	string	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: `"UTC"`.
`timeframe`	No; body/guard requirements still apply	string	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). enum: `["minute", "hour", "day", "week", "month"]`.
`bound_to_timeframe`	No; body/guard requirements still apply	string	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. enum: `["true", "false"]`. default: `"true"`.
`endpoint_id`	No; body/guard requirements still apply	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`api_key_id`	No; body/guard requirements still apply	JSON	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`login_username`	No; body/guard requirements still apply	JSON	Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob
`expand`	No; body/guard requirements still apply	JSON	Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required. default: `["time_series"]`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.api_key_id

input.api_key_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.api_key_id anyOf branch 2

input.api_key_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.login_username

input.login_username anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.login_username anyOf branch 2

input.login_username.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_analytics`

Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. prepare_duration reflects queue/prepare time before execution; duration is request execution time. Use with the Queue/Webhooks flow to monitor SLAs. Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer. Available Metrics: The expand parameter accepts these values, grouped by category: Volume - request_count: Total number of requests in the time bucket - success_count: Successful requests (2xx responses) - user_error_count: User errors (4xx responses) - error_count: Server errors (5xx responses) Error type breakdown - startup_error_count: Startup errors (startup timeout, scheduling failure) - connection_error_count: Connection errors (timeout, disconnected, refused) - timeout_error_count: Request timeout errors - runtime_error_count: Runtime errors (internal error, server error) Queue / prepare latency - p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts Request execution latency - p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request Cold boot - cold_boot_count: Requests with cold boot (startup > 1s) - p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles Billing - total_billable_duration: Aggregate billed execution time Key Features: - Selective metric inclusion via expand parameter - Performance metrics (latency percentiles, duration stats) - Reliability metrics (success/error rates, request counts) - Error type breakdown (startup, connection, timeout, runtime) - Cold boot metrics (count, latency percentiles) - Billing duration tracking - Time-bucketed data for trend analysis - Single or multi-model analytics - Flexible date range and timeframe options Common Use Cases: - Monitor model performance and reliability - Generate performance dashboards - Analyze latency trends and patterns - Track error rates and success metrics See Queue API docs for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`start`	No; body/guard requirements still apply	JSON	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`end`	No; body/guard requirements still apply	JSON	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`timezone`	No; body/guard requirements still apply	string	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: `"UTC"`.
`timeframe`	No; body/guard requirements still apply	string	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). enum: `["minute", "hour", "day", "week", "month"]`.
`bound_to_timeframe`	No; body/guard requirements still apply	string	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. enum: `["true", "false"]`. default: `"true"`.
`endpoint_id`	Yes	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`expand`	No; body/guard requirements still apply	JSON	Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required. default: `["time_series", "request_count"]`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_billing_events`

Returns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD). Key Features: - Individual billing event records for each API request - Per-request cost breakdown before and after discounts - Flexible date range filtering - Optional endpoint filtering - Cursor-based pagination for efficient large dataset queries - Limited to 10000 records per page for performance - Date range capped at 90 days per request Common Use Cases: - Audit individual billing events - Track request patterns and volumes - Debug specific requests by ID - Monitor billing unit consumption per request See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`start`	No; body/guard requirements still apply	JSON	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`end`	No; body/guard requirements still apply	JSON	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`endpoint_id`	No; body/guard requirements still apply	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`request_id`	No; body/guard requirements still apply	JSON	Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2
`api_key_id`	No; body/guard requirements still apply	JSON	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`login_username`	No; body/guard requirements still apply	JSON	Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob
`expand`	No; body/guard requirements still apply	JSON	Data to include in the response. Use 'auth_method' for a formatted authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username).
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.request_id

input.request_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.request_id anyOf branch 2

input.request_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.api_key_id

input.api_key_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.api_key_id anyOf branch 2

input.api_key_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.login_username

input.login_username anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.login_username anyOf branch 2

input.login_username.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`delete_request_payloads`

Deletes the IO payloads and associated CDN output files for a specific request. Important: - Only output CDN files are deleted (input files may be used by other requests) - This action is irreversible - Requires authentication with an admin API key What gets deleted: - Request input/output payload data - CDN-hosted output files (images, videos, etc.) What is NOT deleted: - Input CDN files (may be referenced by other requests) Response: - Returns deletion status for each CDN file - Each result includes the file link and any error that occurred Idempotency: - Optional Idempotency-Key header prevents duplicate deletions on retries - Responses cached for 10 minutes per unique key See fal.ai docs for more details about request payloads.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`request_id`	Yes	string	Unique identifier for the request (UUID format) format: `"uuid"`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`list_requests_by_endpoint`

Lists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs). Authentication: Requires API key (user or enterprise). Filters: - Time range via start / end. If start is omitted, defaults to the last 24 hours : unless request_id is provided, in which case the default start bound is widened to 90 days. - Status (success, error, user_error) - Request ID - Pagination via cursor/limit (limit defaults to 50, max 100) Sorting: - By end time (default) or duration Expansions: - Include payloads by adding expand=payloads

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Number of items to return per page (max 100) minimum: `1`. maximum: `100`. default: `50`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor encoding the page number
`endpoint_id`	Yes	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`start`	No; body/guard requirements still apply	JSON	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`end`	No; body/guard requirements still apply	JSON	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`status`	No; body/guard requirements still apply	string	Filter by request status enum: `["success", "error", "user_error"]`.
`request_id`	No; body/guard requirements still apply	string	Filter by specific request ID format: `"uuid"`.
`expand`	No; body/guard requirements still apply	JSON	Fields to expand in the response. Use payloads to include input and output payloads.
`sort_by`	No; body/guard requirements still apply	string	Sort results by end time or duration enum: `["ended_at", "duration"]`. default: `"ended_at"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`search_requests`

Search, filter, and browse your request history. Supports three modes: 1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search. 2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first). 3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity. Filter Options: - endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs) - exclude_api_requests / only_api_requests: Filter by request source Examples: - Semantic text search: ?query=sunset+landscape - Image similarity: ?image_url=https://...&min_similarity=0.5 - Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev - Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`query`	No; body/guard requirements still apply	string	Text search query for semantic search. Mutually exclusive with image_url and video_url.
`image_url`	No; body/guard requirements still apply	string	Image URL for similarity search. Mutually exclusive with query and video_url.
`video_url`	No; body/guard requirements still apply	string	Video URL for similarity search. Mutually exclusive with query and image_url.
`endpoint_id`	No; body/guard requirements still apply	JSON	Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs).
`endpoint`	No; body/guard requirements still apply	string	Deprecated: use `endpoint_id`. Single-endpoint filter retained for backward compatibility. If both are provided, `endpoint_id` wins. Deprecated native compatibility field.
`exclude_api_requests`	No; body/guard requirements still apply	boolean	Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests.
`only_api_requests`	No; body/guard requirements still apply	boolean	Only include requests made via API keys. Mutually exclusive with exclude_api_requests.
`min_similarity`	No; body/guard requirements still apply	['number', 'null']	Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided. minimum: `0`. maximum: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

`list_workflows`

List workflows for the authenticated user with optional search and filtering. Features: - Paginated results with cursor-based pagination - Search by workflow name or title - Filter by model endpoints used in the workflow Authentication: Required. Returns only workflows owned by the authenticated user. Common Use Cases: - Display user's workflow library - Search for specific workflows - Find workflows using particular models

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`search`	No; body/guard requirements still apply	string	Search by workflow name or title
`used_endpoint_ids`	No; body/guard requirements still apply	JSON	Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.used_endpoint_ids

input.used_endpoint_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.used_endpoint_ids anyOf branch 2

input.used_endpoint_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

`create_workflow`

Create a new workflow owned by the authenticated user. Authentication: Required. Common Use Cases: - Save a newly built workflow - Programmatically provision workflows Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Unique workflow name/slug within the user's namespace maxLength: `128`. pattern: `"^[a-zA-Z0-9_-]+$"`.
`title`	No; body/guard requirements still apply	string	Human-readable workflow title minLength: `1`. maxLength: `256`.
`contents`	No; body/guard requirements still apply	object	The workflow definition/configuration object
`is_public`	No; body/guard requirements still apply	boolean	Whether the workflow is publicly visible default: `false`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.contents

Argument	Required	Type	Details
`name`	Yes	string	Internal name of the workflow definition
`version`	Yes	string	Workflow definition format version
`nodes`	Yes	object	Workflow nodes keyed by node id
`output`	Yes	object	Output field mappings keyed by output name
`schema`	Yes	object	Input/output schema for the workflow
`metadata`	No; body/guard requirements still apply	object	Optional workflow metadata

input.contents.nodes

input.contents.nodes.{key}

input.contents.nodes.{key}.{key}

Native JSON value; inspect the full schema for validation.

input.contents.output

input.contents.output.{key}

Native JSON value; inspect the full schema for validation.

input.contents.schema

Argument	Required	Type	Details
`input`	Yes	object	Input fields schema
`output`	Yes	object	Output fields schema

input.contents.schema.input

input.contents.schema.input.{key}

Native JSON value; inspect the full schema for validation.

input.contents.schema.output

input.contents.schema.output.{key}

Native JSON value; inspect the full schema for validation.

input.contents.metadata

input.contents.metadata.{key}

Native JSON value; inspect the full schema for validation.

input.payload

Argument	Required	Type	Details
`name`	Yes	string	Unique workflow name/slug within the user's namespace maxLength: `128`. pattern: `"^[a-zA-Z0-9_-]+$"`.
`title`	Yes	string	Human-readable workflow title minLength: `1`. maxLength: `256`.
`contents`	Yes	object	The workflow definition/configuration object
`is_public`	No; body/guard requirements still apply	boolean	Whether the workflow is publicly visible default: `false`.

input.payload.contents

Argument	Required	Type	Details
`name`	Yes	string	Internal name of the workflow definition
`version`	Yes	string	Workflow definition format version
`nodes`	Yes	object	Workflow nodes keyed by node id
`output`	Yes	object	Output field mappings keyed by output name
`schema`	Yes	object	Input/output schema for the workflow
`metadata`	No; body/guard requirements still apply	object	Optional workflow metadata

input.payload.contents.nodes

input.payload.contents.nodes.{key}

input.payload.contents.nodes.{key}.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.output

input.payload.contents.output.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.schema

Argument	Required	Type	Details
`input`	Yes	object	Input fields schema
`output`	Yes	object	Output fields schema

input.payload.contents.schema.input

input.payload.contents.schema.input.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.schema.output

input.payload.contents.schema.output.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.metadata

input.payload.contents.metadata.{key}

Native JSON value; inspect the full schema for validation.

`get_workflow`

Get detailed information about a specific workflow, including its full contents/definition. Authentication: Required. Common Use Cases: - Load a workflow for editing - View workflow configuration - Export workflow definition

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`username`	Yes	string	The username of the workflow owner maxLength: `128`. pattern: `"^[a-zA-Z0-9_-]+$"`.
`workflow_name`	Yes	string	The workflow name/slug maxLength: `128`. pattern: `"^[a-zA-Z0-9_-]+$"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`list_assets`

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`q`	No; body/guard requirements still apply	string	Text query for hybrid semantic search
`search_image_url`	No; body/guard requirements still apply	string	fal-hosted image URL to use for semantic image search format: `"uri"`.
`search_video_url`	No; body/guard requirements still apply	string	fal-hosted video URL to use for semantic video search format: `"uri"`.
`media_type`	No; body/guard requirements still apply	['array', 'null']	Filter by one or more media types default: `[]`.
`source`	No; body/guard requirements still apply	['array', 'null']	Filter by one or more indexed sources default: `[]`.
`section`	No; body/guard requirements still apply	string	Asset library section to browse enum: `["all-media", "uploads", "favorites", "generated"]`. default: `"all-media"`.
`collection_id`	No; body/guard requirements still apply	string	Collection scope to browse
`character_identifier`	No; body/guard requirements still apply	['array', 'null']	Character identifiers to use as @mention semantic filters default: `[]`.
`tag_id`	No; body/guard requirements still apply	['array', 'null']	Tag IDs to filter by default: `[]`.
`tag_mode`	No; body/guard requirements still apply	string	Whether tag filters match any tag or all tags enum: `["any", "all"]`. default: `"any"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.media_type

input.media_type[]

Asset media type

input.source

input.source[]

Indexed asset source

input.character_identifier

input.character_identifier[]

Native JSON value; inspect the full schema for validation.

input.tag_id

input.tag_id[]

Native JSON value; inspect the full schema for validation.

`list_asset_collections`

List asset collections for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of collections to return minimum: `1`. maximum: `100`. default: `50`.
`offset`	No; body/guard requirements still apply	['integer', 'null']	Number of collections to skip minimum: `0`. default: `0`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`create_asset_collection`

Create asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`parent_collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: `1`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`name`	Yes	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`parent_collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: `1`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL

`get_asset_collection`

Get asset collection for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`update_asset_collection`

Update asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL

`delete_asset_collection`

Delete asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`get_asset_collection_hierarchy`

Get the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`favorite_asset_collection`

Favorite an asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`unfavorite_asset_collection`

Unfavorite an asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`move_asset_collection`

Move a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`parent_collection_id`	No; body/guard requirements still apply	['string', 'null']	Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`parent_collection_id`	Yes	['string', 'null']	Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: `1`.

`list_asset_collection_assets`

Browse assets in a collection for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`q`	No; body/guard requirements still apply	string	Text query for hybrid semantic search
`search_image_url`	No; body/guard requirements still apply	string	fal-hosted image URL to use for semantic image search format: `"uri"`.
`search_video_url`	No; body/guard requirements still apply	string	fal-hosted video URL to use for semantic video search format: `"uri"`.
`media_type`	No; body/guard requirements still apply	['array', 'null']	Filter by one or more media types default: `[]`.
`source`	No; body/guard requirements still apply	['array', 'null']	Filter by one or more indexed sources default: `[]`.
`section`	No; body/guard requirements still apply	string	Asset library section to browse enum: `["all-media", "uploads", "favorites", "generated"]`. default: `"all-media"`.
`character_identifier`	No; body/guard requirements still apply	['array', 'null']	Character identifiers to use as @mention semantic filters default: `[]`.
`tag_id`	No; body/guard requirements still apply	['array', 'null']	Tag IDs to filter by default: `[]`.
`tag_mode`	No; body/guard requirements still apply	string	Whether tag filters match any tag or all tags enum: `["any", "all"]`. default: `"any"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.media_type

input.media_type[]

Asset media type

input.source

input.source[]

Indexed asset source

input.character_identifier

input.character_identifier[]

Native JSON value; inspect the full schema for validation.

input.tag_id

input.tag_id[]

Native JSON value; inspect the full schema for validation.

`add_asset_to_collection`

Add an asset to a manual or character collection. Provide a request ID or vector ID; unresolved references are materialized before local collection state is added. For character collections, the asset is added by applying the character tag.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`remove_asset_from_collection`

Remove an asset from a manual or character collection by request ID or vector ID.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`collection_id`	Yes	string	Collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`list_asset_characters`

List asset characters for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of collections to return minimum: `1`. maximum: `100`. default: `50`.
`offset`	No; body/guard requirements still apply	['integer', 'null']	Number of collections to skip minimum: `0`. default: `0`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`create_asset_character`

Create 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.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Character display name minLength: `1`. maxLength: `255`.
`identifier`	No; body/guard requirements still apply	['string', 'null']	Optional @mention identifier for the character maxLength: `64`.
`description`	No; body/guard requirements still apply	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	No; body/guard requirements still apply	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.reference_images

input.reference_images[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument	Required	Type	Details
`name`	Yes	string	Character display name minLength: `1`. maxLength: `255`.
`identifier`	No; body/guard requirements still apply	['string', 'null']	Optional @mention identifier for the character maxLength: `64`.
`description`	Yes	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	Yes	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.

input.payload.reference_images

input.payload.reference_images[]

Native JSON value; inspect the full schema for validation.

`update_asset_character`

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.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`character_id`	Yes	string	Character collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Character display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	No; body/guard requirements still apply	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.reference_images

input.reference_images[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Character display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	No; body/guard requirements still apply	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.

input.payload.reference_images

input.payload.reference_images[]

Native JSON value; inspect the full schema for validation.

`get_asset_character`

Get asset character for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`character_id`	Yes	string	Character collection ID minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`delete_asset_character`

Delete asset character for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`character_id`	Yes	string	Character collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`favorite_asset_character`

Favorite an asset character for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`character_id`	Yes	string	Character collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`unfavorite_asset_character`

Unfavorite an asset character for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`character_id`	Yes	string	Character collection ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`list_asset_tags`

List asset tags for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`create_asset_tag`

Create asset tag for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Tag name minLength: `1`. maxLength: `50`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`name`	Yes	string	Tag name minLength: `1`. maxLength: `50`.

`set_asset_tags_for_asset`

Set tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`tag_ids`	No; body/guard requirements still apply	array	Full replacement set of tag IDs
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.tag_ids

input.tag_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`tag_ids`	Yes	array	Full replacement set of tag IDs

input.payload.tag_ids

input.payload.tag_ids[]

Native JSON value; inspect the full schema for validation.

`update_asset_tag`

Update asset tag for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`tag_id`	Yes	string	Tag ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`name`	No; body/guard requirements still apply	string	Tag name minLength: `1`. maxLength: `50`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Tag name minLength: `1`. maxLength: `50`.

`delete_asset_tag`

Delete asset tag for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`tag_id`	Yes	string	Tag ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.

`upload_asset`

Upload asset for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`url`	No; body/guard requirements still apply	string	fal-hosted media URL to ingest into the asset library format: `"uri"`.
`type`	No; body/guard requirements still apply	string	Media type for the uploaded asset enum: `["image", "video", "audio", "3d"]`.
`prompt`	No; body/guard requirements still apply	['string', 'null']	Optional caller-provided caption or description to index with the uploaded asset minLength: `1`. maxLength: `2000`.
`collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional manual collection ID to add the uploaded asset to
`favorite`	No; body/guard requirements still apply	boolean	Whether to favorite the uploaded asset immediately default: `false`.
`tag_ids`	No; body/guard requirements still apply	array	Tag IDs to assign to the uploaded asset default: `[]`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.tag_ids

input.tag_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument	Required	Type	Details
`url`	Yes	string	fal-hosted media URL to ingest into the asset library format: `"uri"`.
`type`	Yes	string	Media type for the uploaded asset enum: `["image", "video", "audio", "3d"]`.
`prompt`	No; body/guard requirements still apply	['string', 'null']	Optional caller-provided caption or description to index with the uploaded asset minLength: `1`. maxLength: `2000`.
`collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional manual collection ID to add the uploaded asset to
`favorite`	No; body/guard requirements still apply	boolean	Whether to favorite the uploaded asset immediately default: `false`.
`tag_ids`	No; body/guard requirements still apply	array	Tag IDs to assign to the uploaded asset default: `[]`.

input.payload.tag_ids

input.payload.tag_ids[]

Native JSON value; inspect the full schema for validation.

`get_asset`

Get an asset document by vector ID from the authenticated user's fal Assets library. The vector may exist only in Turbopuffer; in that case the response returns the Turbopuffer document with empty local state.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`vector_id`	Yes	string	Vector ID minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`get_asset_lineage`

Get the derivation lineage of an asset by asset ID: the inputs it was generated from, the generation requests along the way, and any referenced characters, traversed recursively up to depth levels. Deleted or expired ancestors stay in the graph flagged as tombstones; inputs that were never captured appear as external inputs.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`asset_id`	Yes	string	Asset ID minLength: `1`.
`depth`	No; body/guard requirements still apply	integer	Maximum traversal depth (levels of derivation edges) minimum: `1`. maximum: `5`. default: `5`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`favorite_asset`

Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`unfavorite_asset`

Unfavorite an asset by request ID or vector ID.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`list_asset_tags_for_asset`

List tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`vector_id`	Yes	string	Vector ID minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`assign_asset_tag`

Assign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`tag_id`	Yes	string	Tag ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`unassign_asset_tag`

Unassign a tag from an asset by request ID or vector ID.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`tag_id`	Yes	string	Tag ID minLength: `1`.
`Idempotency_Key`	No; body/guard requirements still apply	string	Optional idempotency key for safe request retries
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.payload

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

`get_storage_file_acl`

Returns the Access Control List currently applied to a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users are returned as nicknames where possible. Authentication: Required. The API key must have the assets:read permission.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`url`	Yes	string	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: `"uri"`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`set_storage_file_acl`

Replaces the Access Control List of a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide. Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent. Authentication: Required. The API key must have the assets:write permission.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`url`	Yes	string	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: `"uri"`.
`default`	No; body/guard requirements still apply	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.rules

input.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

input.payload

Argument	Required	Type	Details
`default`	Yes	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.

input.payload.rules

input.payload.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

`sign_storage_file_url`

Creates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files. The signature is valid for expiration_seconds (up to 7 days). Authentication: Required. The API key must have the assets:read permission.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`url`	Yes	string	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: `"uri"`.
`expiration_seconds`	No; body/guard requirements still apply	integer	How long the signed URL stays valid, in seconds (max 7 days) minimum: `1`. maximum: `604800`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.
`output_file`	Yes	string	Required absolute new owner-private file; signed credential URL is never echoed. minLength: `1`.

input.payload

Argument	Required	Type	Details
`expiration_seconds`	Yes	integer	How long the signed URL stays valid, in seconds (max 7 days) minimum: `1`. maximum: `604800`.

`get_storage_settings`

Returns the account-level storage lifecycle settings applied to newly uploaded fal CDN files: - expiration_duration_seconds: how long files live before being automatically deleted (null disables auto-expiration). - initial_acl: the default ACL applied to new uploads (null means the system default, which is public). Both fields are null when the account has never saved settings. Authentication: Required. The API key must have the account:settings:read permission.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`update_storage_settings`

Replaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration. ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent. These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests. Authentication: Required. The API key must have the account:settings:write permission.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	['object', 'null']	Default ACL applied to newly uploaded files. Null uses the system default (public).
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No; body/guard requirements still apply	boolean	Must be true for the requested mutation, paid work or private output file.
`payload`	No; body/guard requirements still apply	object	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No; body/guard requirements still apply	string	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: `1`.

input.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.

input.initial_acl.rules

input.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

input.payload

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	['object', 'null']	Default ACL applied to newly uploaded files. Null uses the system default (public).

input.payload.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.

input.payload.initial_acl.rules

input.payload.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

`get_account_billing`

Returns billing information for the authenticated account. Use the expand parameter to include additional details. Expandable Fields: - credits : Current credit balance and currency Common Use Cases: - Monitor available credit balance programmatically - Display balance in custom dashboards

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`expand`	No; body/guard requirements still apply	JSON	Data to include in the response. Use 'credits' to include current credit balance.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_organization_teams`

Returns the list of teams in your organization with their details. > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - List all teams within the organization - Identify the organization's root team via is_org_root - View team usernames and display names See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

`get_organization_usage`

Returns paginated usage records across all teams and product lines in your organization, with each record attributed to a specific team via the username field and a product line via the product field. Covers all three fal product lines: - model_apis : model API endpoint calls (e.g. fal-ai/flux/dev) - serverless : fal Serverless SDK billing - compute : fal Compute (raw instance time) > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - Organization-wide usage data across all teams and products - Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method - Per-team and per-product attribution on every usage record - Paginated time series and aggregate summary views See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`limit`	No; body/guard requirements still apply	integer	Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: `1`.
`cursor`	No; body/guard requirements still apply	string	Pagination cursor from previous response. Encodes the page number.
`start`	No; body/guard requirements still apply	JSON	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`end`	No; body/guard requirements still apply	JSON	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`timezone`	No; body/guard requirements still apply	string	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: `"UTC"`.
`timeframe`	No; body/guard requirements still apply	string	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). enum: `["minute", "hour", "day", "week", "month"]`.
`bound_to_timeframe`	No; body/guard requirements still apply	string	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. enum: `["true", "false"]`. default: `"true"`.
`endpoint_id`	No; body/guard requirements still apply	JSON	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`api_key_id`	No; body/guard requirements still apply	JSON	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`team_username`	No; body/guard requirements still apply	JSON	Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams.
`product`	No; body/guard requirements still apply	JSON	Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute).
`expand`	No; body/guard requirements still apply	JSON	Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required. default: `["time_series"]`.
`account`	No; body/guard requirements still apply	string	Exact private account key profile label, not an authenticated provider owner ID.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.api_key_id

input.api_key_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.api_key_id anyOf branch 2

input.api_key_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.team_username

input.team_username anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.team_username anyOf branch 2

input.team_username.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.product

input.product anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.product anyOf branch 2

input.product.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_model_info`

Exact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.

`run_model`

Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

input.lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.lifecycle.initial_acl.rules

input.lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`submit_job`

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

input.lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.lifecycle.initial_acl.rules

input.lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`generate_image`

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

input.lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.lifecycle.initial_acl.rules

input.lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`generate_video`

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

input.lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.lifecycle.initial_acl.rules

input.lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`get_job_status`

One read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`request_id`	Yes	string	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: `"^[A-Za-z0-9_-]{1,128}$"`.
`logs`	No; body/guard requirements still apply	boolean	Include native provider logs only when requested. default: `false`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.

`get_job_result`

One result read using the receipt/model root. No wait loop, media download, re-submission or auto-upload. Signed credential URLs are redacted; ordinary output media URLs remain account data.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`request_id`	Yes	string	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: `"^[A-Za-z0-9_-]{1,128}$"`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.

`cancel_job`

Confirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`request_id`	Yes	string	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: `"^[A-Za-z0-9_-]{1,128}$"`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

`upload_file`

Confirmed selected absolute regular non-symlink local file, 1 byte–20 MiB. Uses pinned SDK upload-initiation protocol then a credential-free HTTPS fal.media PUT with redirects refused. No remote URL ingestion, base64 model output, multipart retries or automatic generation.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`file_path`	Yes	string	Absolute selected local media file, regular/non-symlink, 1 byte–20 MiB. minLength: `1`.
`content_type`	Yes	string	Plain MIME type matching the selected media. pattern: `"^[a-zA-Z0-9.+-]+/[a-zA-Z0-9.+-]+$"`.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.

input.lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.lifecycle.initial_acl.rules

input.lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`list_accounts`

Local labels/default/auth method only. No keys, token paths, real provider identities or network request.

Policy: Read/helper; no explicit mutation approval.

Native JSON value; inspect the full schema for validation.

`get_operation_schema`

Local current native method/path/query/header/body schema and exact provenance. No credential or provider request.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`operation`	Yes	string	Native field; use the reviewed provider reference. enum: ["search_models", "get_pricing", "estimate_pricing", "get_usage", "get_analytics", "get_billing_events", "delete_request_payloads", "list_requests_by_endpoint", "search_requests", "list_workflows", "create_workflow", "get_workflow", "list_assets", "list_asset_collections", "create_asset_collection", "get_asset_collection", "update_asset_collection", "delete_asset_collection", "get_asset_collection_hierarchy", "favorite_asset_collection", "unfavorite_asset_collection", "move_asset_collection", "list_asset_collection_assets", "add_asset_to_collection", "remove_asset_from_collection", "list_asset_characters", "create_asset_character", "update_asset_character", "get_asset_character", "delete_asset_character", "favorite_asset_character", "unfavorite_asset_character", "list_asset_tags", "create_asset_tag", "set_asset_tags_for_asset", "update_asset_tag", "delete_asset_tag", "upload_asset", "get_asset", "get_asset_lineage", "favorite_asset", "unfavorite_asset", "list_asset_tags_for_asset", "assign_asset_tag", "unassign_asset_tag", "get_storage_file_acl", "set_storage_file_acl", "sign_storage_file_url", "get_storage_settings", "update_storage_settings", "get_account_billing", "get_organization_teams", "get_organization_usage"].

`preview_generation_batch`

Read-only current schema validation and native unit-pricing lookup for all requested async jobs. Hash binds ordered exact inputs/lifecycle/store-IO/profile label/current schemas/unit quotes. Unit pricing is not final cost or a spending cap. No generation, file write or key ownership validation.

Policy: Read/helper; no explicit mutation approval.

Argument	Required	Type	Details
`tasks`	Yes	array	One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget. minItems: `1`. maxItems: `10`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.

input.tasks

input.tasks[]

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.

input.tasks[].lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.tasks[].lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.tasks[].lifecycle.initial_acl.rules

input.tasks[].lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

`submit_generation_batch`

Confirmed one-to-ten async jobs. Refetch all current schemas/unit quotes and validate all before first paid submission; refuse changed hash. Submit sequentially, stop on first failure, report known request IDs/failed and unattempted indices. No polling, retries, rollback, continuation or budget guarantee.

Policy: Confirmed operation; read-only hides and directly refuses it.

Argument	Required	Type	Details
`tasks`	Yes	array	One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget. minItems: `1`. maxItems: `10`.
`account`	No; body/guard requirements still apply	string	Exact configured isolated API-key profile label.
`confirm`	No; body/guard requirements still apply	boolean	Explicit approval for the requested paid work, mutation, upload or private file.
`review_sha256`	Yes	string	Native field; use the reviewed provider reference. pattern: `"^[a-f0-9]{64}$"`.

input.tasks

input.tasks[]

Argument	Required	Type	Details
`model_id`	Yes	string	Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: `3`. maxLength: `240`.
`input`	Yes	object	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`lifecycle`	No; body/guard requirements still apply	object	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`store_io`	No; body/guard requirements still apply	boolean	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: `false`.

input.tasks[].lifecycle

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Native field; use the reviewed provider reference. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	object	Native field; use the reviewed provider reference.

input.tasks[].lifecycle.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	Native field; use the reviewed provider reference. maxItems: `100`.

input.tasks[].lifecycle.initial_acl.rules

input.tasks[].lifecycle.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	Native field; use the reviewed provider reference. minLength: `1`.
`decision`	Yes	string	Native field; use the reviewed provider reference. enum: `["allow", "forbid", "hide"]`.

Native `search_models`: GET /models

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`endpoint_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`q`	False	{"type": "string", "description": "Free-text search query to filter models by name, description, or category"}
query	`category`	False	{"type": "string", "description": "Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')"}
query	`status`	False	{"type": "string", "enum": ["active", "deprecated"], "description": "Filter models by status - omit to include all statuses"}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Fields to expand in the response. Supported values: 'openapi-3.0' (includes full OpenAPI 3.0 schema in 'openapi' field), 'enterprise_status' (includes enterprise readiness status)"}

Native `get_pricing`: GET /models/pricing

Location	Parameter	Required	Native shape
query	`endpoint_id`	True	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}

Native `estimate_pricing`: POST /models/pricing/estimate

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native body required: False. Complete body sources cannot mix.

body oneOf branch 1

Argument	Required	Type	Details
`estimate_type`	Yes	string	Estimate type: historical API pricing based on past usage patterns enum: `["historical_api_price"]`.
`endpoints`	Yes	object	Map of endpoint IDs to call quantities

body.oneOf1.endpoints

body.oneOf1.endpoints.{key}

Argument	Required	Type	Details
`call_quantity`	Yes	integer	Number of API calls to estimate (regardless of units per call) minimum: `1`.

body oneOf branch 2

Argument	Required	Type	Details
`estimate_type`	Yes	string	Estimate type: unit price calculation based on billing units enum: `["unit_price"]`.
`endpoints`	Yes	object	Map of endpoint IDs to unit quantities

body.oneOf2.endpoints

body.oneOf2.endpoints.{key}

Argument	Required	Type	Details
`unit_quantity`	Yes	number	Number of billing units expected (e.g., number of images, videos, etc.) minimum: `1e-06`.

Native `get_usage`: GET /models/usage

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`start`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."}
query	`end`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time."}
query	`timezone`	False	{"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."}
query	`timeframe`	False	{"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d)."}
query	`bound_to_timeframe`	False	{"type": "string", "enum": ["true", "false"], "default": "true", "description": "Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided."}
query	`endpoint_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`api_key_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2"}
query	`login_username`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob"}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series"], "description": "Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required."}

Native `get_analytics`: GET /models/analytics

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`start`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."}
query	`end`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time."}
query	`timezone`	False	{"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."}
query	`timeframe`	False	{"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d)."}
query	`bound_to_timeframe`	False	{"type": "string", "enum": ["true", "false"], "default": "true", "description": "Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided."}
query	`endpoint_id`	True	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series", "request_count"], "description": "Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required."}

Native `get_billing_events`: GET /models/billing-events

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`start`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."}
query	`end`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time."}
query	`endpoint_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`request_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2"}
query	`api_key_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2"}
query	`login_username`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob"}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Data to include in the response. Use 'auth_method' for a formatted authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username)."}

Native `delete_request_payloads`: DELETE /models/requests/{request_id}/payloads

Location	Parameter	Required	Native shape
path	`request_id`	True	{"type": "string", "format": "uuid", "description": "Unique identifier for the request (UUID format)"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `list_requests_by_endpoint`: GET /models/requests/by-endpoint

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Number of items to return per page (max 100)"}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor encoding the page number"}
query	`endpoint_id`	True	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`start`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."}
query	`end`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time."}
query	`status`	False	{"type": "string", "enum": ["success", "error", "user_error"], "description": "Filter by request status"}
query	`request_id`	False	{"type": "string", "format": "uuid", "description": "Filter by specific request ID"}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Fields to expand in the response. Use payloads to include input and output payloads."}
query	`sort_by`	False	{"type": "string", "enum": ["ended_at", "duration"], "default": "ended_at", "description": "Sort results by end time or duration"}

Native `search_requests`: GET /models/requests/search

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`query`	False	{"type": "string", "description": "Text search query for semantic search. Mutually exclusive with image_url and video_url."}
query	`image_url`	False	{"type": "string", "description": "Image URL for similarity search. Mutually exclusive with query and video_url."}
query	`video_url`	False	{"type": "string", "description": "Video URL for similarity search. Mutually exclusive with query and image_url."}
query	`endpoint_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs)."}
query	`endpoint`	False	{"type": "string", "description": "Deprecated: use `endpoint_id`. Single-endpoint filter retained for backward compatibility. If both are provided, `endpoint_id` wins.", "deprecated": true}
query	`exclude_api_requests`	False	{"type": "boolean", "description": "Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests."}
query	`only_api_requests`	False	{"type": "boolean", "description": "Only include requests made via API keys. Mutually exclusive with exclude_api_requests."}
query	`min_similarity`	False	{"type": ["number", "null"], "minimum": 0, "maximum": 1, "description": "Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided."}

Native `list_workflows`: GET /workflows

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`search`	False	{"type": "string", "description": "Search by workflow name or title"}
query	`used_endpoint_ids`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values."}

Native `create_workflow`: POST /workflows

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	Yes	string	Unique workflow name/slug within the user's namespace maxLength: `128`. pattern: `"^[a-zA-Z0-9_-]+$"`.
`title`	Yes	string	Human-readable workflow title minLength: `1`. maxLength: `256`.
`contents`	Yes	object	The workflow definition/configuration object
`is_public`	No; body/guard requirements still apply	boolean	Whether the workflow is publicly visible default: `false`.

body.contents

Argument	Required	Type	Details
`name`	Yes	string	Internal name of the workflow definition
`version`	Yes	string	Workflow definition format version
`nodes`	Yes	object	Workflow nodes keyed by node id
`output`	Yes	object	Output field mappings keyed by output name
`schema`	Yes	object	Input/output schema for the workflow
`metadata`	No; body/guard requirements still apply	object	Optional workflow metadata

body.contents.nodes

body.contents.nodes.{key}

body.contents.nodes.{key}.{key}

Native JSON value; inspect the full schema for validation.

body.contents.output

body.contents.output.{key}

Native JSON value; inspect the full schema for validation.

body.contents.schema

Argument	Required	Type	Details
`input`	Yes	object	Input fields schema
`output`	Yes	object	Output fields schema

body.contents.schema.input

body.contents.schema.input.{key}

Native JSON value; inspect the full schema for validation.

body.contents.schema.output

body.contents.schema.output.{key}

Native JSON value; inspect the full schema for validation.

body.contents.metadata

body.contents.metadata.{key}

Native JSON value; inspect the full schema for validation.

Native `get_workflow`: GET /workflows/{username}/{workflow_name}

Location	Parameter	Required	Native shape
path	`username`	True	{"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The username of the workflow owner"}
path	`workflow_name`	True	{"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The workflow name/slug"}

Native `list_assets`: GET /assets

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`q`	False	{"type": "string", "description": "Text query for hybrid semantic search"}
query	`search_image_url`	False	{"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"}
query	`search_video_url`	False	{"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"}
query	`media_type`	False	{"type": ["array", "null"], "items": {"type": "string", "enum": ["image", "video", "audio", "3d"], "description": "Asset media type"}, "default": [], "description": "Filter by one or more media types"}
query	`source`	False	{"type": ["array", "null"], "items": {"type": "string", "enum": ["upload", "response", "request"], "description": "Indexed asset source"}, "default": [], "description": "Filter by one or more indexed sources"}
query	`section`	False	{"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"}
query	`collection_id`	False	{"type": "string", "description": "Collection scope to browse"}
query	`character_identifier`	False	{"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"}
query	`tag_id`	False	{"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"}
query	`tag_mode`	False	{"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"}

Native `list_asset_collections`: GET /assets/collections

List asset collections for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"}
query	`offset`	False	{"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"}

Native `create_asset_collection`: POST /assets/collections

Create asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	Yes	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`parent_collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: `1`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL

Native `get_asset_collection`: GET /assets/collections/{collection_id}

Get asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}

Native `update_asset_collection`: PATCH /assets/collections/{collection_id}

Update asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Collection display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	['string', 'null']	Optional collection description
`icon`	No; body/guard requirements still apply	['string', 'null']	Optional collection icon
`color`	No; body/guard requirements still apply	['string', 'null']	Optional collection color
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the collection format: `"uri"`.
`filters`	No; body/guard requirements still apply	JSON	Assets filter DSL

Native `delete_asset_collection`: DELETE /assets/collections/{collection_id}

Delete asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `get_asset_collection_hierarchy`: GET /assets/collections/{collection_id}/hierarchy

Get the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}

Native `favorite_asset_collection`: POST /assets/collections/{collection_id}/favorite

Favorite an asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `unfavorite_asset_collection`: POST /assets/collections/{collection_id}/unfavorite

Unfavorite an asset collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `move_asset_collection`: POST /assets/collections/{collection_id}/move

Move a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`parent_collection_id`	Yes	['string', 'null']	Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: `1`.

Native `list_asset_collection_assets`: GET /assets/collections/{collection_id}/assets

Browse assets in a collection for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`q`	False	{"type": "string", "description": "Text query for hybrid semantic search"}
query	`search_image_url`	False	{"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"}
query	`search_video_url`	False	{"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"}
query	`media_type`	False	{"type": ["array", "null"], "items": {"type": "string", "enum": ["image", "video", "audio", "3d"], "description": "Asset media type"}, "default": [], "description": "Filter by one or more media types"}
query	`source`	False	{"type": ["array", "null"], "items": {"type": "string", "enum": ["upload", "response", "request"], "description": "Indexed asset source"}, "default": [], "description": "Filter by one or more indexed sources"}
query	`section`	False	{"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"}
query	`character_identifier`	False	{"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"}
query	`tag_id`	False	{"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"}
query	`tag_mode`	False	{"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"}

Native `add_asset_to_collection`: POST /assets/collections/{collection_id}/assets

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `remove_asset_from_collection`: DELETE /assets/collections/{collection_id}/assets

Remove an asset from a manual or character collection by request ID or vector ID.

Location	Parameter	Required	Native shape
path	`collection_id`	True	{"type": "string", "minLength": 1, "description": "Collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `list_asset_characters`: GET /assets/characters

List asset characters for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"}
query	`offset`	False	{"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"}

Native `create_asset_character`: POST /assets/characters

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	Yes	string	Character display name minLength: `1`. maxLength: `255`.
`identifier`	No; body/guard requirements still apply	['string', 'null']	Optional @mention identifier for the character maxLength: `64`.
`description`	Yes	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	Yes	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.

body.reference_images

body.reference_images[]

Native JSON value; inspect the full schema for validation.

Native `update_asset_character`: PATCH /assets/characters/{character_id}

Location	Parameter	Required	Native shape
path	`character_id`	True	{"type": "string", "minLength": 1, "description": "Character collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Character display name minLength: `1`. maxLength: `255`.
`description`	No; body/guard requirements still apply	string	Text description used for character semantic matching minLength: `1`. maxLength: `2000`.
`reference_images`	No; body/guard requirements still apply	array	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. minItems: `1`. maxItems: `20`.
`cover_image_url`	No; body/guard requirements still apply	['string', 'null']	Optional fal-hosted cover image URL for the character format: `"uri"`.

body.reference_images

body.reference_images[]

Native JSON value; inspect the full schema for validation.

Native `get_asset_character`: GET /assets/characters/{character_id}

Get asset character for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`character_id`	True	{"type": "string", "minLength": 1, "description": "Character collection ID"}

Native `delete_asset_character`: DELETE /assets/characters/{character_id}

Delete asset character for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`character_id`	True	{"type": "string", "minLength": 1, "description": "Character collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `favorite_asset_character`: POST /assets/characters/{character_id}/favorite

Favorite an asset character for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`character_id`	True	{"type": "string", "minLength": 1, "description": "Character collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `unfavorite_asset_character`: POST /assets/characters/{character_id}/unfavorite

Unfavorite an asset character for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`character_id`	True	{"type": "string", "minLength": 1, "description": "Character collection ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `list_asset_tags`: GET /assets/tags

List asset tags for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native `create_asset_tag`: POST /assets/tags

Create asset tag for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	Yes	string	Tag name minLength: `1`. maxLength: `50`.

Native `set_asset_tags_for_asset`: PUT /assets/tags

Set tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.
`tag_ids`	Yes	array	Full replacement set of tag IDs

body.tag_ids

body.tag_ids[]

Native JSON value; inspect the full schema for validation.

Native `update_asset_tag`: PATCH /assets/tags/{tag_id}

Update asset tag for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`tag_id`	True	{"type": "string", "minLength": 1, "description": "Tag ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`name`	No; body/guard requirements still apply	string	Tag name minLength: `1`. maxLength: `50`.

Native `delete_asset_tag`: DELETE /assets/tags/{tag_id}

Delete asset tag for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
path	`tag_id`	True	{"type": "string", "minLength": 1, "description": "Tag ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native `upload_asset`: POST /assets/uploads

Upload asset for the authenticated user's fal Assets library.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`url`	Yes	string	fal-hosted media URL to ingest into the asset library format: `"uri"`.
`type`	Yes	string	Media type for the uploaded asset enum: `["image", "video", "audio", "3d"]`.
`prompt`	No; body/guard requirements still apply	['string', 'null']	Optional caller-provided caption or description to index with the uploaded asset minLength: `1`. maxLength: `2000`.
`collection_id`	No; body/guard requirements still apply	['string', 'null']	Optional manual collection ID to add the uploaded asset to
`favorite`	No; body/guard requirements still apply	boolean	Whether to favorite the uploaded asset immediately default: `false`.
`tag_ids`	No; body/guard requirements still apply	array	Tag IDs to assign to the uploaded asset default: `[]`.

body.tag_ids

body.tag_ids[]

Native JSON value; inspect the full schema for validation.

Native `get_asset`: GET /assets/{vector_id}

Location	Parameter	Required	Native shape
path	`vector_id`	True	{"type": "string", "minLength": 1, "description": "Vector ID"}

Native `get_asset_lineage`: GET /assets/{asset_id}/lineage

Location	Parameter	Required	Native shape
path	`asset_id`	True	{"type": "string", "minLength": 1, "description": "Asset ID"}
query	`depth`	False	{"type": "integer", "minimum": 1, "maximum": 5, "default": 5, "description": "Maximum traversal depth (levels of derivation edges)"}

Native `favorite_asset`: POST /assets/favorite

Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `unfavorite_asset`: POST /assets/unfavorite

Unfavorite an asset by request ID or vector ID.

Location	Parameter	Required	Native shape
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `list_asset_tags_for_asset`: GET /assets/{vector_id}/tags

List tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.

Location	Parameter	Required	Native shape
path	`vector_id`	True	{"type": "string", "minLength": 1, "description": "Vector ID"}

Native `assign_asset_tag`: POST /assets/tags/{tag_id}/assign

Assign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Location	Parameter	Required	Native shape
path	`tag_id`	True	{"type": "string", "minLength": 1, "description": "Tag ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `unassign_asset_tag`: DELETE /assets/tags/{tag_id}/assign

Unassign a tag from an asset by request ID or vector ID.

Location	Parameter	Required	Native shape
path	`tag_id`	True	{"type": "string", "minLength": 1, "description": "Tag ID"}
header	`Idempotency-Key`	False	{"type": "string", "description": "Optional idempotency key for safe request retries"}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`request_id`	No; body/guard requirements still apply	string	Request ID to save as an asset before mutating minLength: `1`.
`vector_id`	No; body/guard requirements still apply	string	Vector ID to save as an asset before mutating minLength: `1`.

Native `get_storage_file_acl`: GET /storage/files/acl

Location	Parameter	Required	Native shape
query	`url`	True	{"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."}

Native `set_storage_file_acl`: PUT /storage/files/acl

Location	Parameter	Required	Native shape
query	`url`	True	{"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`default`	Yes	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.

body.rules

body.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

Native `sign_storage_file_url`: POST /storage/files/sign

Location	Parameter	Required	Native shape
query	`url`	True	{"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."}

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`expiration_seconds`	Yes	integer	How long the signed URL stays valid, in seconds (max 7 days) minimum: `1`. maximum: `604800`.

Native `get_storage_settings`: GET /storage/settings

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native `update_storage_settings`: PUT /storage/settings

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native body required: True. Complete body sources cannot mix.

Argument	Required	Type	Details
`expiration_duration_seconds`	No; body/guard requirements still apply	['integer', 'null']	Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: `1`.
`initial_acl`	No; body/guard requirements still apply	['object', 'null']	Default ACL applied to newly uploaded files. Null uses the system default (public).

body.initial_acl

Argument	Required	Type	Details
`default`	Yes	string	Fallback decision when no user-specific rule matches enum: `["allow", "forbid", "hide"]`.
`rules`	No; body/guard requirements still apply	array	User-specific overrides to the default decision default: `[]`.

body.initial_acl.rules

body.initial_acl.rules[]

Argument	Required	Type	Details
`user`	Yes	string	User nickname or user ID the rule applies to minLength: `1`.
`decision`	Yes	string	Access decision applied to this user enum: `["allow", "forbid", "hide"]`.

Native `get_account_billing`: GET /account/billing

Location	Parameter	Required	Native shape
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Data to include in the response. Use 'credits' to include current credit balance."}

Native `get_organization_teams`: GET /organization/teams

Location	Parameter	Required	Native shape
Native request	No path/query/header arguments	No	See required body below

Native `get_organization_usage`: GET /organization/usage

Location	Parameter	Required	Native shape
query	`limit`	False	{"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."}
query	`cursor`	False	{"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."}
query	`start`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."}
query	`end`	False	{"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time."}
query	`timezone`	False	{"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."}
query	`timeframe`	False	{"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d)."}
query	`bound_to_timeframe`	False	{"type": "string", "enum": ["true", "false"], "default": "true", "description": "Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided."}
query	`endpoint_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2"}
query	`api_key_id`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2"}
query	`team_username`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams."}
query	`product`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute)."}
query	`expand`	False	{"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series"], "description": "Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required."}

9. Model and asset workflows

Deliberate model selection

Search the current catalog, get exact model info/schema and pricing, then supply its native input fields. An image endpoint may use image_url, start_image_url, images or other model-specific fields; a wrapper should not guess them. Input validation proves schema compatibility, not prompt quality, rights, reachable input URLs, output appearance or available credits.

Receipt-driven generation

Queue submission creates one billable job and returns its receipt. Preserve model_id, selected account and request_id. Read status once and request the result after COMPLETED; do not resubmit to poll. Status/result/cancel use the SDK's owner/app root, removing inference subpaths. This corrects the old full-model-path queue URL. Cancel only requested jobs; acceptance cannot guarantee a refund or stop processing.

Assets versus CDN files

upload_file sends a chosen local input to the CDN. upload_asset ingests an existing fal-hosted media URL into the account's Assets library with native type/collection/tags/caption. These are different operations and approvals. Browse before altering a collection, tag or character; inspect native IDs, nullable fields and current ownership.

Private media access

Read the target file ACL before explicitly changing it. set_storage_file_acl and update_storage_settings can replace policies: send the full desired native configuration because omitted/null settings can clear previous choices. Native signing creates access authority even for an ACL-restricted file; save it only to a chosen new private file and share it only when requested.

fal-ai-cli get-job-status --model-id fal-ai/flux/dev --request-id YOUR_REQUEST_ID --account work --agent
fal-ai-cli get-job-result --model-id fal-ai/flux/dev --request-id YOUR_REQUEST_ID --account work --agent
fal-ai-cli list-assets --help
fal-ai-cli schema update-storage-settings

10. Exact reviewed batches and pagination

preview_generation_batch reads current model metadata/schema for every task and native unit quotes, validates all inputs and creates a canonical SHA-256. It binds ordered exact inputs, model IDs, lifecycle/store-IO settings, selected profile label, current input-schema hashes, native unit quotes and the packaged API snapshot. It performs no paid generation or file write.

submit_generation_batch requires explicit confirmation and the matching hash. It repeats all preflight reads before any paid POST; schema/price/profile/order/input drift refuses the batch. It then queues sequentially and stops at first failure with known request IDs, failed index and unattempted indices. Earlier requests may still execute/spend credits; the failed request may have an unknown outcome. There is no rollback, cancellation, retry, implicit continuation or final cost reservation.

One to ten jobs is a request-count bound, not an output/price ceiling. Unit quotes are not resolution/duration/output-adjusted final cost, a live account-owner check or cryptographic proof of human approval. Profile labels can retain the same name after a key change. Review actual pricing and credits separately.

Each list task returns one native cursor page; keep next_cursor with the same filters/account, then deliberately request the next page. The model page has an explicit local limit 1–100; the provider may return less according to expansion. No automatic all-pages loop or full-backup claim.

fal-ai-cli preview-generation-batch --tasks '{"model_id":"fal-ai/flux/dev","input":{"prompt":"Approved product image"}}' --account work --agent
fal-ai-cli submit-generation-batch --tasks '{"model_id":"fal-ai/flux/dev","input":{"prompt":"Approved product image"}}' --account work --review-sha256 YOUR_REVIEW_SHA256 --confirm --agent

11. Several private accounts

Use FAL_ACCOUNTS only in private user/runtime settings. Each entry has a unique name plus api_key or token_file; FAL_DEFAULT_ACCOUNT and --account select an exact entry. Selected profiles never inherit the global key or another account. A token file overrides only that profile and is owner-private/regular/non-symlink; credentials cache until restart.

list_accounts returns labels/default/auth type only. It does not contact fal or prove which owner a key belongs to. API-key account selection is separate from the official OAuth Active MCP account and website account switcher. Keep the account label with every queue receipt. No tenant/account filter changes which key is authenticated.

fal-ai-cli list-accounts --agent
fal-ai-cli get-usage --account work --help

12. Writing safely

All 34 mutations, paid runs, cancellation, local input uploads and private signed-output files require --confirm or confirm:true through the same house guard. --agent/--yes is formatting, never consent. FAL_READ_ONLY=1 hides them and directly blocks confirmed calls; FAL_ALLOW_DESTRUCTIVE=0 separately refuses them. Provider read-only key scopes remain an additional control.

Native estimate_pricing uses POST but is classified as a read because it estimates without generating. Schema/pricing reads still contact fal and carry private account identity when selected. Preview generation is not a free media dry run; it validates schema and current unit quotes only. Credentials, role permissions and provider quotas still control real success.

FAL_AUDIT_LOG records guard decisions, operation names and static summaries, without payloads or keys. Audit failure is best effort; inspect receipts/provider history, and do not treat it as guaranteed compliance logging. Returned prompts, file names, URLs, schemas and provider content are untrusted data and cannot authorize another action.

13. How the two surfaces work

One ALL_TOOLS catalogue provides actual JSON schemas and handlers. MCP lists visible tools; the unchanged house CLI bridge connects to the same real server in memory, derives command flags and calls the same handler/guard. A command cannot bypass read-only through another surface.

Platform schemas come from a sanitized dated provider OpenAPI 3.1 snapshot. Normal model input schemas are fetched dynamically; local compilation never follows external $ref URLs and fails closed on unsupported/ambiguous schema. Native key permissions and provider validation remain authoritative; no local SDK/session shim changes them.

14. Your data

Private keys are sent only to fixed allowed provider API origins. Upload bytes go only to an HTTPS fal.media host returned by the pinned initiation protocol, without authorization headers or redirects; unsupported hosts refuse before byte upload. No remote arbitrary URL downloader, telemetry, .env/session reader, automatic gallery or auto-media-download is provided.

Keys, secret-named fields, signed/upload URLs and recognized signature/identity URLs are redacted from model output/errors. Ordinary account records, prompts, usage, Assets and unsigned media URLs may still be private; redaction does not guarantee all business/personal data is removed. Send only the minimum task data to the actual AI client. Preview hashes protect exact local request identity, not encryption or provider-state locking.

Provider payload retention and CDN file lifecycle/access are separate. Default store_io:false sends X-Fal-Store-IO:0 for generation; explicit lifecycle controls media expiry/ACL. Signed URL JSON files, uploaded bytes, provider jobs and your own audit logs persist independently of npm uninstallation. Keep private files/parent directories and Windows ACLs restricted.

15. Environment variables

Setting	Effect
`FAL_KEY`	Private account API key; ignored as a fallback when named profiles are explicitly configured.
`FAL_TOKEN_FILE`	Absolute owner-private regular token-only file; overrides selected direct key.
`FAL_ACCOUNTS`	Private unique {name,api_key,token_file} account profiles.
`FAL_DEFAULT_ACCOUNT`	Exact selected profile label; provider owner is not inferred.
`FAL_READ_ONLY`	1/true hides and directly refuses every non-read task.
`FAL_ALLOW_DESTRUCTIVE`	0/false refuses confirmed paid/mutating/file-write tasks.
`FAL_AUDIT_LOG`	Optional best-effort append-only guard decision file, no payload/key.
`FAL_REQUEST_TIMEOUT_MS`	Default 30000; 100–300000 permitted; no auto retry.
`FAL_MIN_REQUEST_INTERVAL_MS`	Default 350; 0–10000 permitted; process-wide request spacing, not a provider/cross-process limiter.

16. Updates and removal

Use npx -y @thenavidm/fal-ai-mcp-cli@latest for fresh launch resolution, and reconnect/restart existing processes. Global installs need npm update -g @thenavidm/fal-ai-mcp-cli; a versioned desktop extension needs an explicit updated bundle. Inspect release notes before a major upgrade.

Remove the exact MCP registration/skill/global package or desktop extension when requested. Revoke intended provider keys/OAuth separately. Do not delete other account connections. Removing tooling does not cancel generation, refund credits, delete provider media/payloads or private signed files, or undo account/Assets changes.

npm update -g @thenavidm/fal-ai-mcp-cli
fal-ai-cli --version
# Remove only when requested
codex mcp remove fal-ai
npm uninstall -g @thenavidm/fal-ai-mcp-cli

17. Troubleshooting

Symptom	Check and resolution
Binary/Node missing	Node22+, npm global executable PATH; reopen terminal, use npm.cmd if PowerShell policy requires.
Public models work but Assets fail	Catalog is public; verify intended API key/account and per-operation native permissions.
401/403	Check key ownership, revocation, permissions and endpoint eligibility; no cross-account fallback.
429	Respect provider guidance; local pacing is not shared account concurrency/quota enforcement.
Input schema error	Read exact current get_model_info output; native field names differ per model.
Schema unavailable/ambiguous	Paid call fails closed; official clients may support that endpoint differently. No fallback bypass.
Review mismatch	Current inputs/schema/unit price/profile/order changed; preview the actual requested batch again.
Unknown generation outcome	Preserve known receipt and inspect provider history before any explicit repeat.
Job result not ready	Read status once, then fetch result after COMPLETED; do not submit a replacement to poll.
Native queue path differs	Status/result/cancel use owner/app root from current SDK, not full inference subpath.
File upload refused	Absolute non-symlink regular file 1 byte–20 MiB, correct MIME; no multipart/URL upload shortcut.
Signed output path exists	Choose a new private path; existing files are never overwritten.
Changed storage policy	Native replacement may clear omitted settings; read current configuration and send full desired values.
GUI/remote config fails	That runtime needs private settings, filesystem path and Node runtime; terminal environment is separate.

18. API coverage and comparisons

Offering	Reviewed surface	Useful capabilities and limits
Official model MCP	Current OAuth relay; 11 publicly listed tools, checked 2026-10-03	Model discovery/schema/pricing/docs/recommendations, generation, queue/result/cancel and uploads. Active MCP account isolation and prepared signed local upload already exist. Public listed count is not authenticated tools/list. Its example prompt asks a model for approval; docs explicitly say that prompt is not a server-side gate.
Official Platform MCP	Hosted read-only API-key account/serverless surface	Existing account diagnostics, spend, requests and files. Provider permissions still apply. Different product scope from model OAuth; do not call it a generation-only duplicate.
genmedia CLI	Provider-linked v0.7.0, source 63ef5e5b6a72df984c78dfa7fe8e6ed3c03647c0	Cross-platform binaries, dynamic flags/model schemas, smart prompt routing, queue, file upload/download, pricing/docs, gallery, skills, Assets and local encrypted key config. An actual pinned run handler with current SDK 1.10.1 constructed one intercepted paid POST without a confirmation flag. No provider outcome or compiled-binary paid task was run.
Official Python fal CLI	Separate deployment/application CLI	Serverless app management and fal api inference; this is distinct from genmedia. Deployment privileges, machine configuration and application lifecycle are outside this creative companion.
Community MCP + CLI	@sebgrosjean/fal 3.0.0; source 175db5a858e9321107a446a5b43a2252abda274a	Seven reviewed MCP tools plus task CLI, model discovery, native submit/status/result/cancel/upload, shortcuts and local output downloads. Source inspection is not runtime/task-token evidence; no shared exact current-schema/price/profile review boundary found in inspected source.
This owned companion	Shared CLI/local stdio MCP and versioned desktop bundle	66 tasks: 32 reads and 34 explicitly confirmed operations, 53 selected current native platform routes plus 13 creative/account/batch helpers. Mandatory shared approval/direct read-only refusal, isolated account keys, current dynamic input validation, exact ordered generation review, Assets/ACL control and private signed-URL delivery. No hosted OAuth, prompt smart-routing, automatic media download/gallery, serverless deployment or measured token superiority.

Build criterion: useful repeatable improvements that are demonstrated, while acknowledging what the official clients already ship. CLI availability, model count, token estimates and SEO alone do not establish a reason to duplicate fal. The official run-command fixture attempted one intercepted POST with dummy credentials; our same submit_job is blocked by the common guard before schema lookup until the caller explicitly confirms. Current model MCP docs also distinguish prompt-level approval from a server gate. This supports the local policy boundary, not universal superiority or a successful paid workload comparison.

Pinned SDK @fal-ai/client 1.10.1 determines current queue owner/app-root construction and upload initiation. This runtime uses reviewed native HTTP rather than the upstream SDK retry/automatic-file helpers; no vendor source code is copied. Dynamic model schemas are fetched on demand, validated before paid calls and included by hash in reviewed batches. Native Assets metadata remains separate from an uploaded input file.

The pinned provider platform snapshot has 82 operations. This package selects 53 creative platform operations: models/pricing/estimation/usage/requests, workflows, every documented Assets endpoint and storage ACL/expiry, plus account billing and organization usage/team reads. Thirteen helpers add model inspection/execution/queue/local upload/private labels/native-schema lookup/reviewed batches. Serverless/compute/key administration, streaming log/file APIs and CSV FOCUS/model-access-control report wrappers are outside this package. This is explicit scope, not total API parity or 66 unique native HTTP routes.

19. Versions and migration

Component	Reviewed version
Package/desktop manifest	2.0.0
Node runtime	>=22
MCP SDK	1.32.0
Ajv / formats	8.20.0 / 3.0.1
TypeScript / Vitest	7.0.2 / 5.0.3
Desktop builder	2.1.2
Official SDK comparison	@fal-ai/client 1.10.1
Official genmedia comparison	0.7.0
Community MCP/CLI comparison	@sebgrosjean/fal 3.0.0
Native platform snapshot	OpenAPI3.1 / APIv1, checked 2026-10-03

2.0.0 is a deliberate major replacement of the private legacy 1.0.0 MCP. All nine tool names remain. search_models uses current native q/cursor/endpoint_id/expand, not old query without cursor. generate_image/generate_video now require explicit model_id and exact input; they return a queue receipt instead of guessing fields, using stale defaults or waiting implicitly. get_job_result reads once; old wait/max_wait_seconds and video wait_for_result are removed. run_model remains one synchronous paid request with a bounded timeout. Status/result/cancel correct the old full-model-subpath URLs to SDK owner/app roots.

Every paid/mutating/file operation now needs explicit approval, uses strict named-account keys and current schemas. Automatic retries, implicit polling, old output summarization, copied popular-model tables and universal every-model claims are removed. Existing receipts should remain with their original account/model; no history or private settings are imported into the public repo. See CHANGELOG.md and RELEASE-CHECKLIST.md.

20. FAQ

A shared fal.ai task CLI, local stdio MCP and versioned desktop bundle with 66 tasks, current schemas, private accounts and mandatory operation approval.

Yes. Current OAuth model generation, separate read-only API-key Platform MCP and public documentation MCP have distinct scopes. This companion adds shared local policies and reviewed workflows.

Yes. Provider-linked genmedia offers model/Assets workflows and cross-platform binaries; the separate Python fal CLI manages applications and inference. CLI absence is not our build criterion.

Verified common confirmation/read-only enforcement, strict private key profiles, exact ordered current-schema/price reviews and file-only signed-credential delivery support recurring creator workflows.

Node22+ local stdio/CLI on macOS, Windows and Linux. INSTALL covers Codex, Claude Code/Desktop, Cursor, VS Code, Windsurf, Zed, Gemini, Cline and Docker. Remote-only clients use the official relay.

No. Codex registers the same stdio npm package directly. Claude clients are additional supported setups, not prerequisites.

No. Current public model catalog/schema reads can be anonymous. Private Assets/billing/generation permissions and key owner require their own safe checks.

Yes. Exact unique FAL_ACCOUNTS profiles select only their own key/token file; no inherited global or cross-account fallback occurs. A label does not prove provider owner identity.

No. Generic endpoints use current discoverable native input schemas. Missing, ambiguous, external-reference or uncompileable schema fails closed before paid work; provider eligibility still applies.

2.0 requires explicit model_id and native input. Both generation conveniences queue one job and return a receipt; they do not choose stale defaults, map guessed fields or automatically wait/download.

No. Save the receipt/account/model, read status once and fetch results after completion. Never resubmit to check progress; another submission can spend credits again.

Ordered inputs/model IDs/lifecycle/store-IO, selected profile label, current schema hashes, unit quotes and packaged snapshot. It is not final pricing, ownership proof, key fingerprint or cryptographic human approval.

No. One-to-ten job limit is not an output/credit ceiling. Unit quotes vary by actual duration/resolution/output units. Review cost separately before approval.

Execution stops with known receipt IDs, failed index and unattempted tasks. Earlier jobs may continue spending credits; failed submission can have unknown outcome. No replay/rollback/automatic cancellation.

Yes. FAL_READ_ONLY hides all 34 confirmed operations and the common guard directly refuses confirmed calls too. --agent/--yes never authorize paid work.

No. Account/lifecycle ACL and expiry control CDN access; provider defaults can be public. Local store_io:false controls JSON payload storage separately, not media access.

Chosen regular local input uploads are confirmed and capped at 20 MiB; no arbitrary downloader runs. Signed access credentials are saved only to a requested exclusive private JSON file, never model output.

No. A cancellation receipt does not guarantee processing stopped, eligibility or refunded credits. Inspect provider job/billing state; no automatic retry.

Fresh matched successful Codex task/API-usage measurements remain pending. Schema size, fixture refusals or another client/package’s old numbers cannot establish a saving percentage.

Restart/reconnect npm@latest processes; update global installs/desktop bundles explicitly. Remove only the intended client registration, then revoke keys/OAuth separately and review retained jobs/media/private files.

Questions

Open a sanitized issue. Use SECURITY.md for private reports.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This fal.ai MCP server and CLI is one piece of that system.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

Runtime: MCP TypeScript SDK, Ajv and ajv-formats. Development: TypeScript, Vitest, Vite and MCPB. Exact locked versions appear above. Packaging tools are excluded from desktop runtime.

License

Preserves AGPL-3.0 and existing private legacy history. Read THIRD_PARTY_NOTICES.md. fal.ai service terms and trademarks remain separate.

Available Tools

66 tools

add_asset_to_collectionAdd asset to collectionA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

A3.9/5.0

Behavior4/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 safety profile is covered. The description adds genuine behavioral context beyond that: unresolved references are materialized before local collection state changes, and character collections are mutated by applying a character tag. It omits the confirm-gating requirement, which is left to the schema.

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 core action front-loaded and the collection-type nuance following. No filler, though the materialization sentence and the character-tag sentence could be compressed into one.

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 destructive, non-idempotent mutation with 8 parameters and a nested union body, the description covers the collection-type behavior and reference materialization, and the schema plus annotations carry the rest. It does not mention the confirm requirement or retry/idempotency-key semantics, but with full schema coverage and no output schema those gaps are minor.

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 100%, so the schema already documents all 8 parameters, including the mutually exclusive payload/payload_file/flat-flag body inputs. The description only echoes request_id/vector_id and explains their materialization effect, adding little syntax or format detail beyond the structured fields. Baseline 3 is appropriate.

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 (add) and resource (asset to collection) and goes further by distinguishing two target types: manual versus character collections, noting the character-tag mechanism used for the latter. An agent can tell this apart from the sibling remove_asset_from_collection without opening the schema.

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 tells the caller to supply a request ID or vector ID, which is closer to parameter guidance than to when-to-use guidance. It never names the alternative (remove_asset_from_collection) or states any exclusion, so usage context is implied rather than explicit.

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

assign_asset_tagAssign tag to assetA

Destructive

Assign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

ParametersJSON Schema

Name	Required	Description
`tag_id`	Yes	Tag ID
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`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

TDQS

A3.5/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 safety profile is covered. The description usefully adds that unresolved references are materialized (assets may be created as a side effect), which goes beyond annotations, but it omits that this mutation requires confirm=true, an important behavioral precondition.

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?

Two tight sentences with the core action front-loaded and the reference-resolution caveat immediately after. No filler or redundancy.

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 an 8-parameter destructive mutation with no output schema, the description covers the primary action and the materialization side effect, but leaves the confirm precondition and the distinction from sibling tag tools unaddressed.

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 100%, so the baseline is 3 and every parameter is already documented. The description reiterates the request_id/vector_id materialization behavior but adds no format or mutual-exclusivity detail beyond what the schema already states.

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?

The description states a specific verb+resource ('Assign a tag to an asset') and clarifies the reference-resolution behavior. It is clearly distinguishable in intent, but it never names how it differs from close siblings like set_asset_tags_for_asset or unassign_asset_tag, leaving the agent to infer the distinction.

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 second sentence implies usage ('Provide a request ID or vector ID') and gives a light procedural hint, but there is no explicit when-to-use/when-not guidance and no mention of the confirm requirement or alternatives such as set_asset_tags_for_asset.

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

cancel_jobRequest queue cancellationB

Destructive

Confirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`request_id`	Yes	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths.

TDQS

B3.2/5.0

Behavior4/5

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

The description adds real behavioral context beyond the annotations: the receipt is explicitly not proof that processing stopped or credits were refunded, eligibility depends on current provider state, and retries should not be attempted. This meaningfully supplements destructiveHint=true and idempotentHint=false, though it omits any note on permissions/auth or what happens to already-consumed work.

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, front-loaded with the action and immediately followed by the two caveats that matter most. Nothing is redundant, though the clipped phrasing borders on cryptic and could be slightly more explicit without adding length.

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 destructive, non-idempotent mutation with no output schema, the description supplies the key caveats an agent needs: it may not stop processing, refunds are not guaranteed, and retrying is discouraged. It does not mention the required confirm/account inputs or any failure modes, but the schema covers those.

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 100%, so the schema already documents model_id, request_id, account and confirm in detail. The description's 'Confirmed' wording loosely echoes the confirm flag but adds no syntax, format, or dependency meaning beyond the schema, making the baseline 3 correct.

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

Purpose3/5

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

The phrase 'Confirmed native cancellation request' conveys that this cancels something, and the title 'Request queue cancellation' pins the resource to a queued request/job. However, the description never states a clean verb+resource ('cancels a submitted job') and gives no differentiation from siblings like delete_request_payloads or get_job_status, so the agent must infer the object of cancellation.

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

Usage Guidelines2/5

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

'No retry' and 'current provider state controls eligibility' imply when this call is appropriate and when repeating it is pointless, which is useful. But there is no explicit when-to-use vs alternatives guidance (e.g., cancel vs delete payloads vs just polling status), so the agent gets only fragments of routing logic.

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

create_asset_characterCreate asset characterB

Destructive

ParametersJSON 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	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`identifier`	No	Optional @mention identifier for the character
`description`	No	Text description used for character semantic matching
`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	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.

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 safety profile is covered. The description does add one genuine behavioral fact — 'Unresolved ID references are materialized before character state is added' — but says nothing about the destructive scope of the mutation or the confirm requirement that the schema hints at.

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 sentences, front-loaded with the core action and scoped by library ownership. It is tight overall, though the reference_images sentence duplicates schema text rather than earning its place in the prose.

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 mutation with a nested union body (payload vs. flat flags vs. payload_file) and no output schema, the description is adequate but thin — it omits the mutual-exclusivity constraint between body forms and the meaning of the confirm flag. Those are covered by the schema, so the gap is tolerable rather than fatal.

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 100% across all 10 parameters, including the nested payload object, so the baseline is 3. The description's reference_images guidance ('prefer vector IDs or request IDs... use fal-hosted image URLs only for standalone images') is a verbatim restatement of the schema field description, adding no meaning beyond it.

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?

The description states a specific verb and resource — 'Create an asset character' — and scopes it to 'the authenticated user's fal Assets library', which cleanly separates it from siblings like create_asset_collection or create_asset_tag. It never names an alternative tool, so it stops short of the explicit sibling differentiation a 5 requires.

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?

Usage is only implied by the tool name: you call it when you need a new character. There is no statement of when to prefer create_asset_character over update_asset_character, no prerequisites, and no exclusions. The reference_images advice is about input format, not about tool selection.

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

create_asset_collectionCreate asset collectionC

Destructive

Create asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`icon`	No	Optional collection icon
`name`	No	Collection display name
`color`	No	Optional collection color
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`filters`	No	Assets filter DSL
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`description`	No	Optional collection description
`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 collection
`parent_collection_id`	No	Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection.

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, and the description adds only the 'authenticated user's library' scope. It never explains why a creation is marked destructive, whether nested parent collections have side effects, or that retries are unsafe without the Idempotency_Key — all of which matter for a 12-parameter mutation.

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?

A single front-loaded sentence with no filler. It is efficient, though the brevity is partly under-specification rather than true conciseness.

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

Completeness2/5

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

For a tool with 12 parameters, a nested payload object, mutually exclusive flat/payload/payload_file body modes, and no output schema, one sentence is far too thin. It should at least flag the confirm and idempotency requirements and the body-input exclusivity, even if the schema carries the detail.

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 100%, so all 12 parameters including the nested payload and the mutually exclusive body-input modes are already documented. The description adds no syntax or format detail beyond what the schema provides, so the 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 (create) and resource (asset collection) and scopes it to the authenticated user's fal Assets library. It does not differentiate from siblings like create_asset_character or create_asset_tag, but the resource noun is distinct enough to disambiguate.

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

Usage Guidelines2/5

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

No guidance on when to use this versus create_workflow or the other create_* asset tools, and no mention of the confirm=true prerequisite that the schema implies is required for mutations. The agent is left to infer everything from the schema.

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

create_asset_tagCreate asset tagC

Destructive

Create asset tag for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`name`	No	Tag name
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`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

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds only that the tag lands in the authenticated user's library; it says nothing about the required confirm=true gate, permission requirements, or that creation is non-idempotent despite the Idempotency_Key field.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the economy comes partly from omitting information rather than from tight editing.

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 destructive mutation with six parameters, a nested payload union, and no output schema, the description is thin: it omits the confirm gate, idempotency behavior, and payload-vs-flat-flag exclusivity. The rich schema and annotations carry most of that burden, so it is adequate but clearly incomplete.

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 100% and all six parameters are documented in the schema, including the payload/payload_file mutual exclusivity and the confirm requirement. The description adds no parameter meaning of its own, which is the baseline-3 case when the schema does the heavy lifting.

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 (create) and resource (asset tag) with a clear scope qualifier (the authenticated user's fal Assets library). It implicitly separates itself from update_asset_tag/delete_asset_tag by verb, but never names an alternative, so it stops short of full sibling differentiation.

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

Usage Guidelines2/5

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

No when-to-use, when-not-to-use, or alternative guidance is given. An agent cannot tell from the description whether to use this versus create_asset_collection or set_asset_tags_for_asset, or what prerequisites exist.

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

create_workflowCreate a workflowA

Destructive

Create a new workflow owned by the authenticated user.

Authentication: Required.

Common Use Cases:

Save a newly built workflow
Programmatically provision workflows

Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.

ParametersJSON Schema

Name	Required	Description
`name`	No	Unique workflow name/slug within the user's namespace
`title`	No	Human-readable workflow title
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`contents`	No	The workflow definition/configuration object
`is_public`	No	Whether the workflow is publicly visible
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the bar is lower. The description adds genuine extra context: authentication is required, names must be unique per namespace, and a duplicate name yields a 400 validation error. It omits that the 'confirm' flag must be true for the mutation and that payload/payload_file/flat body are mutually exclusive, so not a full 5.

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 the core action, then organized under bold headers for auth, use cases, and the uniqueness caveat. Every section carries some signal, though the use-case bullets are the weakest and could be trimmed.

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 create tool with nested payload objects, no output schema, and annotations covering the safety profile, the description supplies the two things an agent most needs beyond the schema: auth requirement and the duplicate-name failure mode. Nothing critical to correct invocation is missing.

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 100%, so the schema already documents all 8 parameters including the uniqueness constraint on 'name'. The description's uniqueness note only restates what the schema already says, adding no new syntax or format detail beyond the baseline.

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+resource ('Create a new workflow') and identifies ownership ('owned by the authenticated user'). It is distinguishable from list_workflows/get_workflow by the create verb, but it never names or contrasts those siblings explicitly, so it falls short of a 5.

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 'Common Use Cases' section gives implied context (saving a built workflow, programmatic provisioning), but there is no explicit when-to-use-vs-alternative guidance and no when-not-to-use exclusions. Usage is implied rather than stated.

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

delete_asset_characterDelete asset characterB

Destructive

Delete asset character for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`character_id`	Yes	Character collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.1/5.0

Behavior2/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 safety profile is largely covered structurally. The description adds only the mild scoping note about the authenticated user's library and says nothing about irreversibility, what happens to associated assets, or the required confirm=true gate.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its extreme terseness is part of why behavioral and usage context is missing.

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 destructive single-entity delete with a required ID, 100% schema coverage, and annotations covering safety hints, the description is close to sufficient. It still omits the confirm=true precondition and irreversibility warning, which would be valuable for a destructive operation.

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 100%, so the schema already documents all four parameters including character_id, account, confirm, and Idempotency_Key. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

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?

The description states a specific verb (Delete) and resource (asset character), plus a scope qualifier (the authenticated user's fal Assets library). It is clearly distinguishable from siblings such as delete_asset_collection, delete_asset_tag, or unfavorite_asset_character, though it does not name those siblings explicitly.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives (e.g., delete_asset_collection, remove_asset_from_collection, unfavorite_asset_character), no prerequisites, and no stated exclusions or confirmation requirements. The intended usage is only implied by the verb 'Delete'.

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

delete_asset_collectionDelete asset collectionB

Destructive

Delete asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the library scope but omits meaningful behavioral facts for a destructive call: whether deletion is reversible, whether child collections/assets in the hierarchy are cascaded, and that the schema's confirm flag must be set true.

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?

A single front-loaded sentence with zero filler; the verb and scope land immediately. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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 one-parameter mutation with no output schema and annotations covering the safety profile, the description is minimally sufficient. However, it leaves real ambiguity about cascade behavior over the collection hierarchy and the effect on contained assets, which matters for a destructive operation.

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 100% and all four parameters (account, confirm, collection_id, Idempotency_Key) are documented in the schema, so the baseline is 3. The description adds no param-level meaning such as what happens when confirm is false or how account scoping interacts with collection ownership.

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 (Delete) and resource (asset collection) and scopes it to the authenticated user's fal Assets library. It distinguishes the tool from other deletions like delete_asset_character, delete_asset_tag, and remove_asset_from_collection, though it never explicitly names or contrasts with those siblings.

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

Usage Guidelines2/5

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer on its own whether this is the right call versus remove_asset_from_collection or move_asset_collection, which are different removal semantics.

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

delete_asset_tagDelete asset tagB

Destructive

Delete asset tag for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`tag_id`	Yes	Tag ID
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is fully covered structurally. The description adds only the scope detail (authenticated user's library) and omits notable behaviors such as the required confirm=true gate for the mutation and idempotency-key usage, so it contributes modest value beyond the annotations.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly under-specification rather than true tightness.

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 destructive mutation with no output schema, the annotations cover safety and the schema covers all four parameters, so the description is adequate. However, it omits the confirm=true requirement that gates the operation and any note about what happens to tags currently assigned to assets, leaving a meaningful gap.

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 100%, so tag_id, account, confirm, and Idempotency_Key are already documented in the schema. The description adds no parameter syntax or semantics beyond what is provided there, which is the expected baseline when the schema does the heavy lifting.

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?

The description gives a specific verb (Delete) and resource (asset tag) scoped to the authenticated user's fal Assets library. It is clear on its own, but does not differentiate from close siblings like update_asset_tag or unassign_asset_tag, so an agent must rely on the name alone to route correctly.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as unassign_asset_tag (which removes a tag from an asset rather than deleting the tag itself). The description offers no conditions under which this tool should or should not be chosen.

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

delete_request_payloadsDelete request payloadsA

Destructive

Deletes the IO payloads and associated CDN output files for a specific request.

Important:

Only output CDN files are deleted (input files may be used by other requests)
This action is irreversible
Requires authentication with an admin API key

What gets deleted:

Request input/output payload data
CDN-hosted output files (images, videos, etc.)

What is NOT deleted:

Input CDN files (may be referenced by other requests)

Response:

Returns deletion status for each CDN file
Each result includes the file link and any error that occurred

Idempotency:

Optional Idempotency-Key header prevents duplicate deletions on retries
Responses cached for 10 minutes per unique key

See fal.ai docs for more details about request payloads.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`request_id`	Yes	Unique identifier for the request (UUID format)
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

A4.2/5.0

Behavior5/5

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

Goes well beyond the annotations (destructiveHint, idempotentHint=false, openWorldHint) by disclosing exactly what is destroyed vs preserved, that the action is irreversible, that an admin API key is required, and that idempotency is available only via an optional key with a 10-minute cache window. This is exactly the behavioral detail an agent needs before a destructive call.

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 the core action, then organized into scannable labeled sections (Important, What gets deleted, What is NOT deleted, Response, Idempotency). Slightly long and the closing docs link is optional, but nearly every line carries decision-relevant content.

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?

With no output schema, the description compensates by explaining the return value (per-file deletion status with file link and any error). Combined with the destructive-action caveats, an agent has everything needed to call this 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 description coverage is 100%, so the baseline is 3. The description reinforces the Idempotency-Key behavior and mentions admin-key auth, but adds little syntax or semantics beyond what the schema already documents for request_id, account, and confirm.

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 (deletes) and resources (IO payloads and associated CDN output files) scoped to a specific request. No sibling tool performs this operation, so it is trivially distinguishable, and the 'what gets deleted' / 'what is NOT deleted' breakdown pins down scope precisely.

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?

Provides rich context (irreversible, admin key required, only output files affected) but never explicitly frames when to reach for this tool versus alternatives, nor states any when-not conditions. Usage is implied rather than routed, though the surrounding context is strong.

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

estimate_pricingEstimate costA

Read-onlyIdempotent

Computes cost estimates using one of two methods:

1. Historical API Price (historical_api_price):

Based on historical pricing per API call from past usage patterns
Takes call_quantity (number of API calls) per endpoint
Useful for estimating based on actual historical usage patterns
Example: "How much will 100 calls to flux/dev cost?"

2. Unit Price (unit_price):

Based on unit price × expected billing units from pricing service
Takes unit_quantity (number of billing units like images/videos) per endpoint
Useful when you know the expected output quantity
Example: "How much will 50 images from flux/dev cost?"

Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.

Common Use Cases:

Pre-calculate costs for batch operations
Display cost estimates in user interfaces
Budget planning and cost optimization

See fal.ai pricing for more details.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.

TDQS

A4.3/5.0

Behavior4/5

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

Adds auth requirement (valid API key) and notes custom pricing/discounts may apply - useful context beyond the readOnly/idempotent/destructive annotations. Doesn't describe response format or rate limits, but annotations already establish the safe read-only profile.

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?

Well-structured with bold headers and bullet lists making the two methods scannable. Slightly verbose with redundant examples, but front-loaded and organized.

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 3-param tool with 100% schema coverage and no output schema, the description covers purpose, both methods, examples, auth, and use cases. Could mention response shape, but not a major gap given annotation coverage.

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 100%, so the schema already documents all parameters. The description explains the semantic distinction between call_quantity and unit_quantity, adding real value, but this is largely mirrored in the schema descriptions themselves - baseline 3.

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?

Specific verb (computes cost estimates) plus the two distinct resource/method variants (historical_api_price, unit_price) are named and exemplified. An agent can clearly distinguish this from siblings like get_pricing or get_usage.

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?

Explicitly states when to use each method with concrete examples ('How much will 100 calls...' vs 'How much will 50 images...'). Also names common use cases (batch pre-calc, UI display, budget planning), giving clear context for tool selection.

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

favorite_assetFavorite assetA

Destructive

Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`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

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare a destructive, non-idempotent, open-world mutation. The description adds a genuinely non-obvious behavior: unresolved references are materialized (saved as assets) before favorite state is applied. That is real value beyond the annotations, though it omits the confirm-gate requirement that the schema implies for this mutation.

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?

Two tight sentences with the core action front-loaded and the identifier guidance placed close behind. No filler, though the materialization clause is slightly compressed and could be clearer.

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 7-param mutation with a nested payload, mutually exclusive body inputs, and a confirm gate, the description is thin: it does not mention confirm, payload_file, idempotency, or how the body options interact. The rich schema compensates, keeping this adequate rather than deficient.

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 the schema already documents all 7 params including the nested payload and exclusivity rules. The description only restates the request_id/vector_id choice and adds no format, precedence, or exclusivity detail beyond the schema. Baseline 3 is appropriate.

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+resource ('Favorite an asset') and clarifies the input shapes (request ID or vector ID). It implicitly separates itself from unfavorite_asset, but does not distinguish itself from sibling favorites like favorite_asset_collection or favorite_asset_character, which share nearly identical naming.

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?

It tells the agent which identifier to supply, which is practical input guidance, but gives no when-to-use framing, no exclusions, and no mention of the alternative favorite/unfavorite siblings. Usage is implied by the name rather than stated.

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

favorite_asset_characterFavorite asset characterC

Destructive

Favorite an asset character for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`character_id`	Yes	Character collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely carried by structured data. The description adds nothing about reversibility (unfavorite exists), the confirm=true gate for mutation, or how favoriting affects existing collections, leaving a mutation described in one neutral sentence.

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?

A single front-loaded sentence with no filler or repetition. It is efficient, though arguably under-specified rather than optimally concise for a mutating tool.

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 one-required-param mutation with no output schema, the schema and annotations cover most structured needs, but the description omits the confirm requirement's purpose, reversibility, and any pointer to the unfavorite counterpart. Minimum-viable rather than 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 100%, including the confirm and account semantics, so the baseline of 3 applies. The description adds no extra meaning about character_id format or how account scoping interacts with the authenticated user.

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 (Favorite) and resource (asset character) scoped to the authenticated user's fal Assets library, which is enough to distinguish it from unfavorite_asset_character and the other character tools. It stops short of naming the sibling it replaces, so differentiation relies on 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 Guidelines2/5

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

No guidance on when to use this versus unfavorite_asset_character, list_asset_characters, or edit tools, and no prerequisites such as the required confirm=true flag or idempotency-key usage. The reader must infer all of that from the schema.

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

favorite_asset_collectionFavorite asset collectionB

Destructive

Favorite an asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description adds that the favorite is scoped to the authenticated user's library, which is useful context, but it does not explain the required confirm=true flag or the effect of the destructive/non-idempotent hints.

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?

A single front-loaded sentence with no filler; the verb-resource-scope structure is efficient and immediately parseable.

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?

With annotations covering the mutation safety profile and a fully documented schema, the description is adequate but thin: it omits the mandatory confirm requirement and any note on idempotency/retry behavior that would matter for a non-idempotent write. No output schema exists, so return values need not be described.

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 100%, so the schema already documents account, confirm, collection_id, and Idempotency_Key. The description contributes nothing about parameter meaning, so the 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 (favorite) and resource (asset collection) plus the scope (authenticated user's fal Assets library). It is clearly distinguishable from siblings like unfavorite_asset_collection or create_asset_collection through the verb alone, though the description does not explicitly name those alternatives.

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

Usage Guidelines2/5

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

No when-to-use or when-not-to-use guidance is given; the reader must infer that this applies only to collections not already favorited. The obvious sibling unfavorite_asset_collection is never referenced as the counterpart operation.

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

generate_imageSubmit image generationB

Destructive

ParametersJSON Schema

Name	Required	Description
`input`	Yes	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`store_io`	No	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate.
`lifecycle`	No	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.

TDQS

B3/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real behavioral context the annotations cannot: queue submissions return a receipt only, a synchronous timeout can leave an unknown paid outcome, and there is no retry or polling. That payment-outcome uncertainty is exactly the kind of non-obvious trait an agent needs before invoking.

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

Conciseness3/5

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

The text is compact and free of filler, but it is telegraphic and not front-loaded with the core action; the first clause leads with payment/validation framing instead of what the tool produces. Every clause carries information, yet the phrasing is dense enough to be cryptic on first read.

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 6-parameter tool with nested objects and no output schema, the description covers payment confirmation, validation, and failure semantics reasonably well. However, it only gestures at the return value ('receipt only') and says nothing about the generated image payload or how results are retrieved, leaving a gap the absent output schema would otherwise force it to fill.

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 100%, so the schema already documents all six parameters thoroughly. The description reinforces that exact model_id/input are required and that no fields may be invented or defaulted, which is marginally useful but adds little beyond the schema's own wording.

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

Purpose3/5

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

The title gives the verb+resource ('Submit image generation'), but the description itself is oblique: 'Confirmed paid model request after current native input-schema validation' describes the payment/validation framing rather than plainly stating that it generates an image. It never distinguishes itself from siblings like run_model, submit_job, or generate_video, so an agent must infer the boundary from the title alone.

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

Usage Guidelines2/5

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

The only usage constraint is the negative 'No retry or polling,' plus the implication that confirm must be set for paid work. There is no statement of when to choose this over run_model, submit_job, or generate_video, and no prerequisites beyond the vague 'confirmed paid request.'

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

generate_videoSubmit video generationB

Destructive

ParametersJSON Schema

Name	Required	Description
`input`	Yes	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`store_io`	No	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate.
`lifecycle`	No	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.

TDQS

B3.3/5.0

Behavior4/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 safety profile is covered. The description adds genuinely non-obvious behavior: this is a paid request, queue submissions return a receipt only, and a synchronous timeout may leave an unknown paid outcome with no retry. That is real value beyond the annotations.

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?

Dense but front-loaded: the paid/validated precondition and the required inputs come first, followed by the queue/timeout/no-retry consequences. No sentence is filler, though the jargon-heavy phrasing slightly hurts scannability.

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 destructive, paid, 6-parameter tool with no output schema, the description covers the critical paid-outcome and no-retry behaviors. However it omits how to observe results after a queue receipt (e.g., get_job_status) and says nothing about the confirm/account gating, leaving a follow-up gap.

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 100%, so the schema already documents all six parameters well, including the nested lifecycle/ACL objects. The description only reinforces model_id/input ('do not invent fields or choose a default') without adding format or value semantics, so baseline 3 applies.

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

Purpose3/5

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

The body opens with 'Confirmed paid model request' and only implies the video-generation purpose through the name/title and the passing phrase 'image/video commands.' It never cleanly states a verb+resource like 'generates a video,' and it does not distinguish itself from close siblings such as generate_image or run_model.

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?

It gives implicit operational guidance ('Exact model_id/input required,' 'No retry or polling') that constrains how the agent should behave, but there is no explicit when-to-use vs alternatives, and no routing to get_job_status/cancel_job for follow-up.

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

get_account_billingAccount BillingB

Read-onlyIdempotent

Returns billing information for the authenticated account. Use the expand parameter to include additional details.

Expandable Fields:

credits — Current credit balance and currency

Common Use Cases:

Monitor available credit balance programmatically
Display balance in custom dashboards

ParametersJSON Schema

Name	Required	Description	Default
`expand`	No	Data to include in the response. Use 'credits' to include current credit balance.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without the description. The description adds that `expand=credits` surfaces credit balance and currency, which is useful, but says nothing about authentication requirements beyond 'authenticated account', rate limits, or what happens with multi-account access.

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-loads the core purpose in the first sentence, then uses a bolded expandable-fields block and a use-case list. Structure is easy to scan, though the use-case list is somewhat padding for a two-parameter read tool.

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 simple read-only tool with no output schema, the description covers the main behavior adequately. It is incomplete on the `account` parameter and multi-account handling, which matters for a tool scoped to the 'authenticated account'.

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 100%, so both parameters are already documented in the schema; the description restates the `expand`/`credits` semantics without adding new syntax or format detail. The `account` parameter is not mentioned at all in the description, so no value is added beyond the schema baseline.

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 and resource: it returns billing information for the authenticated account, and names the expandable `credits` field. It does not differentiate itself from close siblings like get_billing_events, get_usage, or get_pricing, so an agent can't route confidently among them from the text 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 'Common Use Cases' section gives implied context (monitoring credit balance, dashboard display) rather than explicit when-to-use guidance. It never states when to prefer this over get_billing_events or get_usage, which are the obvious alternatives.

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

get_analyticsAnalyticsA

Read-onlyIdempotent

Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer.

Available Metrics:

The expand parameter accepts these values, grouped by category:

Volume

request_count: Total number of requests in the time bucket
success_count: Successful requests (2xx responses)
user_error_count: User errors (4xx responses)
error_count: Server errors (5xx responses)

Error type breakdown

startup_error_count: Startup errors (startup timeout, scheduling failure)
connection_error_count: Connection errors (timeout, disconnected, refused)
timeout_error_count: Request timeout errors
runtime_error_count: Runtime errors (internal error, server error)

Queue / prepare latency

p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts

Request execution latency

p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request

Cold boot

cold_boot_count: Requests with cold boot (startup > 1s)
p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles

Billing

total_billable_duration: Aggregate billed execution time

Key Features:

Selective metric inclusion via expand parameter
Performance metrics (latency percentiles, duration stats)
Reliability metrics (success/error rates, request counts)
Error type breakdown (startup, connection, timeout, runtime)
Cold boot metrics (count, latency percentiles)
Billing duration tracking
Time-bucketed data for trend analysis
Single or multi-model analytics
Flexible date range and timeframe options

Common Use Cases:

Monitor model performance and reliability
Generate performance dashboards
Analyze latency trends and patterns
Track error rates and success metrics

See Queue API docs for more details.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`start`	No	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`expand`	No	Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`timezone`	No	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.	UTC
`timeframe`	No	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).
`endpoint_id`	Yes	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`bound_to_timeframe`	No	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided.	true

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds real behavioral context beyond them: only metrics named in 'expand' are populated, and it explains the semantic difference between prepare_duration (queue time) and duration (execution time).

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

Conciseness3/5

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

The metric enumeration earns its place, but the 'Key Features' and 'Common Use Cases' sections largely restate what the metric list and opening paragraph already said, adding bulk rather than new information.

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?

With no output schema and 10 parameters, the description is largely sufficient: it explains metric selection, latency semantics, and time bucketing. Minor gaps remain around pagination (cursor/limit) usage and multi-endpoint behavior, but nothing critical for a read-only analytics call.

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 coverage is 100%, so the baseline is 3, but the description goes further by enumerating every valid 'expand' metric value by category, which the schema's generic expand description does not provide. This materially improves correct metric selection.

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+resource: time-bucketed metrics (request counts, success/error rates, latency percentiles) per model endpoint. An agent can tell this is a read-only performance analytics tool, though it never names siblings like get_usage or get_billing_events to sharpen the boundary.

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?

Provides clear context ('Use with the Queue/Webhooks flow to monitor SLAs') and a list of common use cases (dashboards, latency trends, error tracking). However, it offers no exclusions or explicit routing away from overlapping siblings such as get_usage or get_billing_events.

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

get_assetGet assetA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`vector_id`	Yes	Vector ID

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety profile. The description adds valuable behavioral context by noting that the vector may exist only in Turbopuffer and that the response then returns the Turbopuffer document with empty local state, which is useful edge-case disclosure beyond annotations.

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?

The description consists of two tightly written sentences with no filler. The primary purpose is front-loaded, followed by the edge-case behavior, making every sentence earn its place.

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?

Given the tool's simplicity, 100% schema coverage, and comprehensive annotations, the description is largely complete. It adds the important Turbopuffer fallback behavior and notes the authenticated user's library, though it does not describe the general return shape beyond that edge case; with no output schema, this is a minor gap.

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 100%, so both parameters (account and vector_id) are already documented in the schema. The description mentions 'by vector ID' and 'authenticated user's fal Assets library' but adds no syntax, format, or usage details beyond what the schema provides, warranting the baseline score of 3.

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?

The description states a specific verb ('Get') and resource ('asset document by vector ID from the authenticated user's fal Assets library'), making the purpose clear. However, it does not explicitly differentiate this tool from similar siblings like list_assets or get_asset_lineage, so it falls short of a 5.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives such as list_assets or search_models. It only states what the tool does, leaving the agent to infer usage conditions without any explicit when/when-not context.

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

get_asset_characterGet asset characterC

Read-onlyIdempotent

Get asset character for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`character_id`	Yes	Character collection ID

TDQS

C2.9/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the scope constraint (the authenticated user's library), implying an auth/ownership requirement, but says nothing about not-found behavior or what the returned character contains.

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?

A single short sentence with the resource and scope front-loaded and no filler. It is efficient, though its brevity is partly under-specification rather than discipline.

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 two-parameter read tool with full schema coverage and annotations covering the safety profile, plus no output schema to explain, the description is minimally sufficient. It still omits what an asset character represents and any error semantics, which are the only remaining gaps.

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 100%: character_id and account are both documented in the schema (including the distinction between account key label and provider owner ID). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

Purpose3/5

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

The description states a verb ("Get") and resource ("asset character") plus a scope ("authenticated user's fal Assets library"), so it is not pure tautology. However, it does not clarify what an asset character is or how it differs from the many sibling retrieval tools (get_asset_collection, get_asset, list_asset_characters), leaving the purpose only minimally specified.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus list_asset_characters, get_asset_collection, or get_asset. The description gives no prerequisites, no when-not-to-use condition, and names no alternative, so the agent must infer routing from the name alone.

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

get_asset_collectionGet asset collectionC

Read-onlyIdempotent

Get asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`collection_id`	Yes	Collection ID

TDQS

C2.9/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds only that the read is scoped to the authenticated user's own library, which is mild but real context; it says nothing about what happens for missing/inaccessible collections.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity borders on under-specification rather than maximal information density.

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?

With no output schema, the description should ideally convey what a returned collection contains (assets, metadata, hierarchy), but it does not. Annotations and the schema cover safety and inputs adequately, so the tool is callable, but return expectations remain unstated.

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 100%, so both collection_id and account are documented in the schema (including the account label caveat). The description adds no additional meaning about parameter usage or format, so the baseline 3 applies.

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

Purpose3/5

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

The description states a verb ('Get') and resource ('asset collection') and adds the scope 'for the authenticated user's fal Assets library.' However, it is essentially a restatement of the tool name/title and gives no signal distinguishing it from siblings like list_asset_collections, get_asset_collection_hierarchy, or list_asset_collection_assets.

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

Usage Guidelines2/5

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

There is no guidance on when to call this versus list_asset_collections (all collections) or get_asset_collection_hierarchy (nested structure). No prerequisites, no exclusions, no alternatives are named.

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

get_asset_collection_hierarchyGet asset collection hierarchyA

Read-onlyIdempotent

Get the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`collection_id`	Yes	Collection ID

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral value by disclosing the return shape (descendant subtree plus ancestors ordered top-down to the direct parent), which is important since no output schema exists. It does not mention recursion depth, empty-subtree behavior, or the account parameter's effect on scoping.

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?

One sentence, zero filler, with the primary result (the nested subtree) front-loaded and the secondary result (ancestors) following. Nothing could be removed without losing meaning.

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?

With no output schema and only two parameters, the description carries most of the burden and does so by explaining exactly what comes back. It stops short of covering edge cases an agent might hit, such as depth limits, whether ancestors are returned when the collection is top-level, or how the account parameter scopes the lookup.

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 100%, so both parameters are already documented in the schema, and the description only indirectly indicates that collection_id is the subtree root. It adds nothing about how the account profile parameter affects which hierarchy is returned; the baseline of 3 applies.

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 (get the hierarchy for an asset collection) and disambiguates the generic word 'hierarchy' by spelling out both the nested subtree and the ordered ancestor chain. An agent can distinguish this from get_asset_collection or list_asset_collections 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 Guidelines3/5

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

The description implies the use case (navigating up/down from a collection) but never explicitly says when to reach for this instead of get_asset_collection, list_asset_collections, or list_asset_collection_assets. No prerequisites or exclusions are stated.

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

get_asset_lineageGet asset lineageA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description
`depth`	No	Maximum traversal depth (levels of derivation edges)
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`asset_id`	Yes	Asset ID

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing two important return behaviors: deleted or expired ancestors are retained as flagged tombstones, and never-captured inputs surface as external inputs — context an agent could not infer from the schema.

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?

Two sentences, front-loaded with the core operation and then the edge-case semantics. Every clause carries information; nothing is redundant or restated from the schema.

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?

With no output schema, the description carries the burden of describing the return graph and does so well (inputs, requests, characters, tombstones, external inputs). Annotations cover the safety profile. Minor gap: no note on graph size, performance cost of depth=5, or account-scoping effects, but nothing essential is missing.

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 100%, so asset_id, account, and depth are already documented in the schema; the baseline is 3. The description reinforces that `depth` bounds recursive traversal levels, but adds no new syntax or constraint detail (e.g. cost of higher depth) 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 (get) and resource (derivation lineage of an asset) and then enumerates exactly what the graph contains: inputs, generation requests, referenced characters. This is clearly distinguishable from siblings like get_asset or list_asset_characters, which return the asset or its characters rather than its derivation graph.

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 recursive, derivation-focused nature implies when to use it (tracing provenance upstream from an asset), and the `depth` mention hints at traversal control. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g. get_asset for metadata only), so usage is only implied.

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

get_billing_eventsBilling EventsA

Read-onlyIdempotent

Key Features:

Individual billing event records for each API request
Per-request cost breakdown before and after discounts
Flexible date range filtering
Optional endpoint filtering
Cursor-based pagination for efficient large dataset queries
Limited to 10000 records per page for performance
Date range capped at 90 days per request

Common Use Cases:

Audit individual billing events
Track request patterns and volumes
Debug specific requests by ID
Monitor billing unit consumption per request

See fal.ai docs for more details.

ParametersJSON Schema

Name	Required	Description
`end`	No	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`start`	No	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`expand`	No	Data to include in the response. Use 'auth_method' for a formatted authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username).
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`api_key_id`	No	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`request_id`	No	Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2
`endpoint_id`	No	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`login_username`	No	Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely useful operational context the annotations don't: a 10,000-record page cap, a 90-day date-range cap, cursor pagination, and the shape of the per-record cost breakdown including the nano-USD field. It omits auth/permission requirements and default date-window semantics beyond brief hints.

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?

Well front-loaded: the core behaviour and returned fields come first, then bulleted features and use cases. It is somewhat padded — the 'Individual billing event records for each API request' bullet restates the opening sentence, and the use-case list is somewhat generic — but structure and scannability are good.

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 10-parameter read tool with no output schema, the description covers the pagination model, page/range limits, and the fields returned, which is enough for correct invocation. Missing pieces are minor: no explicit output envelope/pagination response shape and no note on what happens when no filters are supplied.

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 100%, so the schema already explains every parameter (dates, cursor, expand, api_key_id, request_id, endpoint_id, login_username, account) with formats and array syntax. The description adds little parameter-level detail beyond the 90-day range cap, which justifies the baseline 3 rather than higher.

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?

Opens with a specific verb+resource ('Returns paginated individual billing event records') and enumerates the returned fields (request ID, timestamp, endpoint, units, cost breakdown). It implicitly distinguishes itself from aggregate siblings like get_account_billing and get_usage by emphasizing 'individual ... records', but never names an alternative, so a perfect 5 isn't earned.

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?

The 'Common Use Cases' block gives concrete contexts (audit individual billing events, debug specific requests by ID, monitor unit consumption) that tell an agent when this tool fits. However, it provides no exclusions or routing advice against siblings such as get_account_billing or get_usage, so guidance is contextual rather than prescriptive.

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

get_job_resultRead completed queue result onceA

Read-onlyIdempotent

One result read using the receipt/model root. No wait loop, media download, re-submission or auto-upload. Signed credential URLs are redacted; ordinary output media URLs remain account data.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured isolated API-key profile label.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`request_id`	Yes	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond that: no polling/wait loop, no media download, no re-submission, and the fact that signed credential URLs are redacted while ordinary media URLs remain account data. This is meaningful behavioral context the annotations do not supply.

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?

Two tight sentences with the core action front-loaded and the exclusion list packed efficiently. Dense but no wasted filler, though the telegraphic phrasing borders on cryptic.

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 read-only result fetch with annotations covering the safety profile and no output schema to document, the description covers what it does, what it deliberately does not do, and how URLs are handled. Sufficient for correct invocation.

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 100%, so all three parameters (account, model_id, request_id) are already well documented in the schema. The description only alludes to the 'receipt/model root' pairing without adding syntax or format detail, so baseline 3 is appropriate.

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+resource ('One result read') and names the identifier basis ('receipt/model root'), so an agent knows this retrieves a finished job's output. It does not explicitly contrast with the sibling get_job_status, leaving the boundary partly to inference.

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 negatives ('No wait loop, media download, re-submission or auto-upload') implicitly tell the agent this is a one-shot read rather than a poll or resubmit, which narrows usage. However, it never names get_job_status or states the condition under which this tool is preferred, so guidance remains implied.

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

get_job_statusRead queue status onceB

Read-onlyIdempotent

One read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.

ParametersJSON Schema

Name	Required	Description
`logs`	No	Include native provider logs only when requested.
`account`	No	Exact configured isolated API-key profile label.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`request_id`	Yes	Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths.

TDQS

B3.3/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: this is a one-shot read with no automatic polling, it does not trigger a paid re-submission, and it will not fetch an arbitrary status URL. Those cost/side-effect disclosures go beyond the annotations, though the response shape and failure modes remain unstated.

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?

Two tight sentences with the core constraint (one read, no polling) front-loaded and no filler. The compression is aggressive enough that the implementation jargon slightly obscures rather than clarifies, but nothing is wasted.

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?

With no output schema, the description should carry the burden of explaining what a status read returns (queued/running/succeeded/failed) and any throttling expectations for repeated calls; it does not. It covers scope and side effects well but leaves the agent guessing about the payload it will receive.

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 100%, so model_id, request_id, account and logs are already documented in the schema; that sets the baseline at 3. The 'owner/app root, not the full model subpath' clause adds a little context on how request_id/model_id are interpreted, but it is not a material gain over the schema.

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

Purpose3/5

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

The title plus 'One read' conveys that this is a single status fetch, and the negatives (no polling, no paid re-submission, no arbitrary URL) hint it is not submit_job or get_job_result. However, the description never plainly states 'returns the queue status of a previously submitted request_id'; it leans on jargon like 'SDK-compatible owner/app root' and 'full model subpath' that an agent must decode.

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?

'No auto-polling' implies the agent must re-call this itself to track progress, which is real usage guidance, and 'no paid re-submission' warns against using it as a resubmit path. It never names the alternatives (get_job_result, cancel_job) or states when status-checking is appropriate versus fetching a result, so guidance remains implied rather than explicit.

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

get_model_infoInspect current model metadata/schemaC

Read-onlyIdempotent

Exact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact configured isolated API-key profile label.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.

TDQS

C2.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds two genuine behavioral facts beyond that: the schema may be unavailable, and defaults are never generated or inferred. It still omits pagination and return-shape behavior, so it is adequate but not rich.

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

Conciseness3/5

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

Three short sentences with no filler, and the core purpose is front-loaded. However, the opening clause is dense jargon ('OpenAPI expansion') that costs comprehension without adding clarity, and the phrasing is telegraphic rather than sharp.

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?

With no output schema, the description carries some burden for return values, and 'inspect actual native fields' plus the schema-unavailability caveat partially address that. But it never says what fields come back or how OpenAPI expansion manifests, leaving the agent under-informed for a read-only inspection tool.

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 100%, so the required model_id and optional account are fully documented in the schema itself. The description adds no syntax, format, or selection detail beyond the schema, matching the baseline for full-coverage parameters.

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

Purpose3/5

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

The description frames the tool as an 'Exact current catalog lookup with OpenAPI expansion,' which gestures at retrieving model metadata but never states it plainly as a verb+resource. It offers no differentiation from the sibling search_models, so an agent cannot tell the two apart from the description alone. The title helps, but the description itself is jargon-heavy.

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

Usage Guidelines2/5

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

'No generation or inferred model defaults' hints at a boundary but never states when to use this tool versus search_models or get_pricing. There is no explicit when-to-use, when-not-to-use, or named alternative. Usage must be inferred from the title.

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

get_operation_schemaInspect native platform operationC

Read-onlyIdempotent

Local current native method/path/query/header/body schema and exact provenance. No credential or provider request.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes

TDQS

C2.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds 'No credential or provider request,' which reinforces that no network/provider call occurs and no auth is consumed — useful but largely redundant with openWorldHint=false. 'Exact provenance' hints at return content without explaining it, so added value beyond annotations is modest.

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

Conciseness3/5

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

It is short and front-loaded, with no filler sentences, which is good. But the terseness tips into under-specification: two clipped fragments using unexplained terms ('native', 'provenance') leave the core purpose ambiguous, so brevity comes at a cost.

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?

With no output schema, the description is the only source for what is returned, and it does name the schema components (method/path/query/header/body) and provenance. However, it omits any explanation of the required 'operation' parameter and when this tool is useful, leaving the definition adequate but incomplete for a 53-value enum meta-tool.

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 0%, so the single 'operation' parameter has no documentation in the schema; only the enum value names hint at meaning. The description mentions the returned fields (method/path/query/header/body) but never explains what the 'operation' parameter accepts or how it maps to those siblings, so it does not compensate for the coverage gap.

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

Purpose3/5

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

The title 'Inspect native platform operation' plus 'method/path/query/header/body schema' conveys that this returns the schema for a named operation, so the resource is discernible. However, the description opens with the fragment 'Local current native...' which is jargon rather than a verb+resource statement, and it never explicitly says it returns schema metadata rather than performing the operation. It is understandable but not crisp.

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

Usage Guidelines2/5

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

There is no guidance on when to call this instead of the actual sibling tools (search_requests, get_pricing, upload_asset, etc.) whose names appear as enum values. An agent cannot tell from the description whether this is a prerequisite, a debugging aid, or a documentation lookup, and no exclusions are given.

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

get_organization_teamsOrganization TeamsA

Read-onlyIdempotent

Returns the list of teams in your organization with their details.

Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.

Must be called with an admin API key on the organization's root team.

Key Features:

List all teams within the organization
Identify the organization's root team via is_org_root
View team usernames and display names

See fal.ai docs for more details.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds meaningful non-annotation context: the access gate and the admin-key/root-team authentication requirement.

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 the core purpose, then availability and auth constraints, then a key-features list. The docs link and feature bullets are slightly redundant but each carries some information, so it is reasonably efficient.

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?

No output schema exists, so the description usefully names the returned fields (is_org_root, usernames, display names) and the access constraints. It is close to complete for a read-only listing tool, though pagination/return shape is not addressed.

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% and the single 'account' parameter is fully documented in the schema itself. The description adds nothing about the parameter, so the baseline of 3 applies when the schema does all the work.

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 and resource ('Returns the list of teams in your organization with their details') and enumerates the fields returned. It does not explicitly distinguish itself from the listing siblings (e.g., list_accounts), but no sibling lists teams, so confusion is low.

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?

Provides strong context: enterprise-only availability and the requirement to call with an admin API key on the organization's root team. It stops short of naming alternatives or when-not-to-use conditions, but the prerequisite framing is clear.

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

get_organization_usageOrganization UsageA

Read-onlyIdempotent

Covers all three fal product lines:

model_apis — model API endpoint calls (e.g. fal-ai/flux/dev)
serverless — fal Serverless SDK billing
compute — fal Compute (raw instance time)

Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.

Must be called with an admin API key on the organization's root team.

Key Features:

Organization-wide usage data across all teams and products
Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method
Per-team and per-product attribution on every usage record
Paginated time series and aggregate summary views

See fal.ai docs for more details.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`start`	No	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`expand`	No	Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`product`	No	Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute).
`timezone`	No	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.	UTC
`timeframe`	No	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).
`api_key_id`	No	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`endpoint_id`	No	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`team_username`	No	Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams.
`bound_to_timeframe`	No	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided.	true

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the admin-key-on-root-team auth requirement, the enterprise availability gate, pagination behavior, and the fact that every record carries team (username) and product attribution. It stops short of describing rate limits or response envelope details.

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-loads the core purpose, then availability and auth, then features — a sensible ordering. It is on the long side and the 'Key Features' bullet list partially restates the opening paragraph and the filter set already in the schema, which is mild redundancy rather than waste.

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 13-parameter, no-output-schema tool this covers everything an agent needs: auth prerequisite, availability gate, filter dimensions, enumeration of product lines, pagination, and the shape of each returned record. Nothing essential to invoking it 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some meaning on top: it spells out the three product values with descriptions, names the attribution fields returned per record, and groups the filter dimensions (team, product, endpoint, api_key_id, date range, auth method). No extra syntax or format guidance is added, but the added framing is real.

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 ('Returns paginated usage records') and immediately bounds the scope to 'across all teams and product lines in your organization,' which is what separates it from the team-scoped get_usage/get_analytics siblings. The enumerations of the three product lines and the per-record attribution fields leave no ambiguity about what this tool produces.

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 prerequisites and gating conditions: enterprise-only availability and the requirement to call with an admin API key on the organization's root team. It does not, however, explicitly name an alternative tool or state when a sibling (e.g. get_usage for a single team) would be the better choice, so routing is inferred rather than directed.

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

get_pricingPricingA

Read-onlyIdempotent

Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.

Common Use Cases:

Display pricing in user interfaces
Compare pricing across different models
Build cost estimation tools
Check current billing rates

See fal.ai pricing for more details.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`endpoint_id`	Yes	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it explains the two pricing modes (output-based vs GPU-based), the per-billing-unit/currency format, the API-key requirement, and that custom pricing/discounts may apply based on account status.

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

Conciseness3/5

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

The core pricing explanation is front-loaded and earns its place, and auth is clearly flagged. But the four-item 'Common Use Cases' bullet list and the link are largely filler that restates obvious scenarios without adding routing or behavioral information.

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 two-parameter read tool with no output schema, the description is fairly complete: it explains return semantics (per-model billing unit in a given currency), covers the pricing-mode nuance, and states the auth requirement. Only the ambiguity against estimate_pricing keeps it from being fully 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 100%: the schema already documents endpoint_id filtering syntax (1-50 IDs, comma or array) and the account label. The description adds no parameter-level detail, so baseline 3 is correct because the schema does the heavy lifting.

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 and resource ('Returns unit pricing for requested endpoint IDs') and explains the pricing semantics well. However, it never differentiates itself from the close sibling estimate_pricing, so an agent cannot tell from the description alone which of the two to call.

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 'Common Use Cases' list gives implied usage context (UI display, comparison, cost tools), but it reads as generic marketing rather than routing guidance. There is no explicit when-to-use-this-vs-alternative statement, and the obvious alternative estimate_pricing is never mentioned.

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

get_storage_file_aclGet file ACLA

Read-onlyIdempotent

Returns the Access Control List currently applied to a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users are returned as nicknames where possible.

Authentication: Required. The API key must have the assets:read permission.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for going beyond them: it discloses the required auth scope (`assets:read`) and describes the ACL's shape, including the enum of default decisions and nickname resolution. It does not cover error behavior or rate limits, but for a read-only tool this is solid.

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?

Three tight, front-loaded parts: what is returned, how the ACL is composed, and the auth requirement. No filler sentences, and the most important information leads.

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?

With no output schema, the description usefully explains what comes back (default decision values, per-user override rules, nickname resolution) and states the auth requirement; parameters are fully handled by the schema. Only the absence of any routing to the sibling write tool keeps it from a 5.

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 100% – both `url` (format, example, no-query-params constraint) and `account` (label semantics) are fully documented in the schema. The description adds no parameter-level detail, so the baseline of 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?

The description gives a specific verb and resource ('Returns the Access Control List currently applied to a fal CDN file') and even characterizes the return structure (default decision plus per-user overrides). It is clearly distinguishable from set_storage_file_acl, but it never explicitly names that sibling, so differentiation is by inference only.

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?

Usage is implied – you call this to inspect a file's ACL – but there is no explicit when-to-use guidance, no conditions, and no reference to the write counterpart set_storage_file_acl or to sign_storage_file_url. Adequate but with clear gaps.

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

get_storage_settingsGet storage settingsA

Read-onlyIdempotent

Returns the account-level storage lifecycle settings applied to newly uploaded fal CDN files:

expiration_duration_seconds: how long files live before being automatically deleted (null disables auto-expiration).
initial_acl: the default ACL applied to new uploads (null means the system default, which is public).

Both fields are null when the account has never saved settings.

Authentication: Required. The API key must have the account:settings:read permission.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds real value on top: the meaning of each returned field, the null semantics (null disables auto-expiration; null ACL means system default public; both null when never saved), and an explicit required permission. It stops short of describing pagination or response shape, but there is little else to disclose for a simple read.

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 the purpose, then a compact bullet list per returned field, then an auth line. Every sentence earns its place, though the formatting is slightly heavier than a single-field read strictly requires.

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?

With no output schema, the description fully compensates by documenting the returned fields and their null semantics. Auth is stated, and the parameter is covered by the schema. Nothing an agent needs to invoke it correctly is missing.

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 100%, and the single `account` parameter is well documented in the schema as a private account key profile label. The description does not mention the parameter at all, so 3 is the appropriate baseline when the schema carries the semantics.

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 and resource: returns account-level storage lifecycle settings for newly uploaded fal CDN files, and enumerates the two returned fields. It is clearly a read operation, distinguishing it implicitly from update_storage_settings, but it never names that sibling to sharpen the contrast.

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

Usage Guidelines2/5

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

The description explains what the tool returns and the auth it needs, but gives no when-to-use guidance and no routing to alternatives such as update_storage_settings (to change settings) or get_storage_file_acl (for per-file ACLs). The agent must infer the appropriate context.

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

get_usageUsageA

Read-onlyIdempotent

Key Features:

Usage data for all endpoints or filtered by specific endpoint(s)
Flexible date range filtering
User-specific usage tracking
Detailed usage line items with unit quantity, price, and discount breakdown
Paginated results for large datasets

Common Use Cases:

Generate usage reports for all endpoints or specific models
Track usage patterns
Monitor endpoint usage across different auth methods
Build usage dashboards and visualizations

See fal.ai docs for more details.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`start`	No	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`expand`	No	Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`timezone`	No	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.	UTC
`timeframe`	No	Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).
`api_key_id`	No	Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
`endpoint_id`	No	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
`login_username`	No	Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob
`bound_to_timeframe`	No	Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided.	true

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral value on top: it discloses the response fields (billed unit quantity, pre-discount price, cost_subtotal, discount, cost_total with its formula) and pagination, which matters because there is no output schema. It stops short of describing pagination limits or rate behavior.

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

Conciseness3/5

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

The opening paragraph is well front-loaded and earns its place, but the 'Key Features' bullets largely restate that same paragraph (filters, pagination, line-item detail), and the 'Common Use Cases' list is padding. Roughly half the text is redundant with the intro.

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 12-parameter, zero-required read tool with no output schema, the description compensates well by spelling out the returned cost/quantity fields and noting pagination. It is not fully complete because it omits the sibling disambiguation against get_organization_usage/get_analytics and says nothing about page-size limits despite the 'limit' parameter.

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 100%, so the schema already documents all 12 parameters, including the endpoint/user/date/auth filters. The description only echoes those same filter categories ('filters for endpoint, user, date range, and auth method') without adding format, defaulting, or interaction detail, so 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+resource ('Returns paginated usage records for your workspace') and enumerates the filterable dimensions, so the agent knows this is a read/list tool. However, it never differentiates itself from close siblings such as get_organization_usage, get_analytics, or get_billing_events, all of which plausibly return overlapping usage/cost data.

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 'Common Use Cases' block implies when this tool is useful (usage reports, dashboards, auth-method monitoring), which is a step above nothing. But it gives no when-not guidance and never names an alternative tool, leaving the agent to guess whether get_organization_usage or get_analytics is the right sibling for a given query.

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

get_workflowGet workflow detailsA

Read-onlyIdempotent

Get detailed information about a specific workflow, including its full contents/definition.

Authentication: Required.

Common Use Cases:

Load a workflow for editing
View workflow configuration
Export workflow definition

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`username`	Yes	The username of the workflow owner
`workflow_name`	Yes	The workflow name/slug

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that with 'Authentication: Required' and by clarifying that the full contents/definition are returned rather than a summary.

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 the core statement, then short labeled sections. Every sentence is short and readable; the use-case bullets are mildly redundant with the opening sentence but not wasteful.

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?

With no output schema, the description must indicate what comes back, and it does ('full contents/definition'). Auth requirement and scope are covered; the only missing piece is any note on error behavior for a missing workflow or owner.

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 100% and all three parameters are documented in-schema, including the non-obvious distinction that 'account' is a profile label rather than a provider owner ID. The description adds nothing beyond the schema, so the 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 and resource ('Get detailed information about a specific workflow') and even names the payload scope ('full contents/definition'), which distinguishes it from list_workflows and create_workflow in the sibling set. It stops short of explicitly naming those siblings as alternatives, so it is clear but not fully differentiated.

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 'Common Use Cases' bullets (load for editing, view configuration, export) imply when the tool is relevant, but they are fairly generic and restate the purpose rather than giving decision criteria. No exclusions, prerequisites, or named alternatives (e.g. list_workflows) are offered.

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

list_accountsList configured private accountsB

Read-onlyIdempotent

Local labels/default/auth method only. No keys, token paths, real provider identities or network request.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.3/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world traits. The description adds genuinely new behavioral context beyond that: it guarantees no secrets are exposed (no keys, token paths, or real provider identities) and that no network request occurs, which tells the agent the result is locally sanitized data.

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?

A single short sentence with no filler, and the field-scope constraint is front-loaded ahead of the exclusion list. It is fragmentary and slightly cryptic to parse, but every clause earns its place.

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 zero-parameter tool with no output schema, the description should hint at the return shape. It names the field categories returned (label, default flag, auth method) and what is excluded, but never describes the structure or count of results, leaving the response format to inference.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. There are no arguments whose semantics need explaining.

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

Purpose3/5

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

The description never states a verb+resource; it only enumerates the field scope ('Local labels/default/auth method only') and exclusions. The title carries the actual purpose, so an agent must fall back on structured metadata rather than the description to know this lists configured accounts.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no prerequisites, and no mention of any alternative sibling. The description gives no indication of when this tool should be selected over the many other list_* tools.

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

list_asset_charactersList asset charactersB

Read-onlyIdempotent

List asset characters for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of collections to return
`offset`	No	Number of collections to skip
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description only adds the scoping detail that results come from the authenticated user's library, and says nothing about pagination behavior despite limit/offset params.

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?

A single tight sentence with the resource and scope front-loaded and zero filler. It is efficient, though the extreme brevity borders on under-specification rather than ideal conciseness.

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 read-only list tool with annotations covering the safety profile and 100% schema coverage, the definition is minimally viable. It omits pagination semantics and what an 'asset character' actually is, which an agent might need given the many sibling asset-* tools.

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 100%, so all three parameters are already documented in the schema (baseline 3). The description adds no parameter-level detail such as how limit/offset interact or what the account label means, so it neither compensates nor detracts.

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 (List) and resource (asset characters) scoped to the authenticated user's fal Assets library, so an agent can distinguish it from get_asset_character (singular) and the create/update/delete character tools. However, it does not explicitly contrast itself with sibling list tools like list_assets or list_asset_tags, leaving some differentiation to inference.

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

Usage Guidelines2/5

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

The description gives no when-to-use guidance, prerequisites, or alternatives. It never states that this is the enumeration counterpart to get_asset_character or how it relates to collection/tag listing. Usage context is entirely absent.

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

list_asset_collection_assetsBrowse assets in a collectionC

Read-onlyIdempotent

Browse assets in a collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description	Default
`q`	No	Text query for hybrid semantic search
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`source`	No	Filter by one or more indexed sources
`tag_id`	No	Tag IDs to filter by
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`section`	No	Asset library section to browse	all-media
`tag_mode`	No	Whether tag filters match any tag or all tags	any
`media_type`	No	Filter by one or more media types
`collection_id`	Yes	Collection ID
`search_image_url`	No	fal-hosted image URL to use for semantic image search
`search_video_url`	No	fal-hosted video URL to use for semantic video search
`character_identifier`	No	Character identifiers to use as @mention semantic filters

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond the title: it does not mention pagination via cursor, that filters narrow results, or how results are returned, which for a read tool with rich filtering is a real gap.

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?

A single front-loaded sentence with zero filler. It is efficient but borders on under-specification for a tool with this much filtering surface, so not a 5.

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

Completeness2/5

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

This is a 13-parameter, filter-heavy listing tool with no output schema, and the description says nothing about its search/filter capabilities (text query, semantic image/video search, tags, media types, sections) or pagination. The structured fields carry the load, but the prose is too thin for the tool's complexity.

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 100% across all 13 parameters, including enum values, defaults, and the meaning of the cursor and limit fields, so the schema does the heavy lifting. The description contributes no parameter meaning beyond what is already documented, which is the baseline 3 case.

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?

The description states a specific verb (Browse) and resource (assets in a collection) scoped to the user's fal Assets library, which is enough to tell it apart from list_assets and get_asset_collection at a glance. However it does not explicitly name the siblings it differs from, so it stays short of a 5.

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

Usage Guidelines2/5

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

There is no when-to-use guidance and no mention of alternatives. With siblings like list_assets (all assets) and get_asset_collection (collection metadata) present, the agent must infer that this tool returns the members of one collection; nothing in the text confirms that or states when to prefer it.

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

list_asset_collectionsList asset collectionsB

Read-onlyIdempotent

List asset collections for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of collections to return
`offset`	No	Number of collections to skip
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the account-scoping context ('authenticated user's fal Assets library') and says nothing about ordering, pagination behavior, or result shape.

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?

A single front-loaded sentence with no filler or repetition of the title. It is efficient, though its brevity leaves the tool with almost no explanatory content.

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 simple read-only list tool with rich annotations and a fully documented schema, the description covers the essentials. Pagination semantics and the shape of a returned collection are left entirely to the schema, which is acceptable here since no output schema exists but the operation is straightforward.

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 100%, so limit, offset, and account are all documented in the schema itself, including the subtle note that account is a private profile label rather than a provider owner ID. The description adds no parameter meaning beyond that, which is the expected baseline.

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 (List) and resource (asset collections) with scope (authenticated user's fal Assets library), which cleanly separates it from get_asset_collection and list_asset_collection_assets. It stops short of explicitly naming those siblings, so an agent must infer the distinction 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 Guidelines2/5

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

The description offers no when-to-use context, no prerequisites, and no mention of alternatives such as get_asset_collection (single collection) or list_asset_collection_assets (contents of a collection). Usage is only implied by the tool name.

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

list_assetsBrowse assetsB

Read-onlyIdempotent

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

ParametersJSON Schema

Name	Required	Description	Default
`q`	No	Text query for hybrid semantic search
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`source`	No	Filter by one or more indexed sources
`tag_id`	No	Tag IDs to filter by
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`section`	No	Asset library section to browse	all-media
`tag_mode`	No	Whether tag filters match any tag or all tags	any
`media_type`	No	Filter by one or more media types
`collection_id`	No	Collection scope to browse
`search_image_url`	No	fal-hosted image URL to use for semantic image search
`search_video_url`	No	fal-hosted video URL to use for semantic video search
`character_identifier`	No	Character identifiers to use as @mention semantic filters

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds that this spans semantic search plus multiple library sections, but says nothing about pagination behavior, ordering, or result shape that the annotations don't already imply.

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?

A single front-loaded sentence with no filler, and the primary verb launches the sentence. It is appropriately sized, though it offers no structural cues for the complex 13-parameter surface.

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 13-parameter, no-required-input search tool with no output schema, the description covers purpose and scope but omits anything about returned results or pagination semantics (the cursor is undocumented outside the schema). Adequate but with clear gaps given the tool's complexity.

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 100%, so all 13 parameters are already documented at the schema level. The description's mention of media, uploads, favorites, collections and tags loosely maps to the 'section' and filter params but adds no syntax, format, or interaction detail beyond the schema; 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 (browse and semantically search) and resource (fal Assets) and enumerates the scopes covered (media, uploads, favorites, collections, tags, character references). It's clear what the tool does, but it never names a sibling such as list_asset_collection_assets or get_asset to sharpen differentiation from the many adjacent asset tools.

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

Usage Guidelines2/5

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

The description lists what can be browsed but gives no when-to-use guidance, no selection criteria versus alternatives (e.g. list_asset_collection_assets, search_requests), and no exclusions. The enumeration of sections implies scope but stops short of routing the agent.

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

list_asset_tagsList asset tagsB

Read-onlyIdempotent

List asset tags for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the authentication/library scoping, but says nothing about ordering, pagination, or result size for a list operation.

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?

A single efficient sentence with the scope front-loaded and no filler. It is arguably too terse for a list tool but wastes nothing.

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?

There is no output schema, so the description should say something about what is returned (tag list shape, ordering, pagination), but it does not. With annotations covering safety and the schema covering the one parameter, the gaps are modest but real.

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% and the sole 'account' parameter already carries a detailed description distinguishing a profile label from a provider owner ID. The description adds no parameter meaning beyond the schema, so the baseline of 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?

The description gives a clear verb+resource ('List asset tags') and scopes it to 'the authenticated user's fal Assets library', which implicitly distinguishes it from the per-asset sibling list_asset_tags_for_asset. However, it never names that sibling or explicitly states it returns all tags across the library rather than tags on a single asset.

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?

Usage is only implied by the 'Assets library' scope; there is no explicit statement of when to use this versus list_asset_tags_for_asset or the create/update/delete tag siblings. The library-level scope gives a hint but no alternatives or exclusions are named.

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

list_asset_tags_for_assetList tags for an assetA

Read-onlyIdempotent

List tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`vector_id`	Yes	Vector ID

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing a real edge case: vectors not saved as assets return an empty tag list, which prevents misreading an empty result as an error. It still doesn't mention ordering or pagination.

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?

Two short sentences, zero filler. The core action is front-loaded and the edge case follows it immediately, so nothing needs re-reading.

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 small read-only lookup with full annotation coverage and no output schema, the description covers the essential behavior including the empty-result case. It leaves the shape of a returned tag and any ordering/pagination unspecified, which is a minor gap given the tool's simplicity.

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 100%, including a careful note on the 'account' parameter distinguishing it from a provider owner ID, so the schema carries the parameter burden. The description only restates that lookup is by vector ID, adding no new semantics, which is the expected baseline when the schema is complete.

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?

The description gives a specific verb and resource ('List tags for an asset') and adds a scoping detail ('by vector ID'), so the agent knows it retrieves tags for one identified asset. It does not explicitly distinguish itself from the sibling list_asset_tags, which likely lists tag definitions rather than per-asset assignments, so it stops short of a 5.

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?

Usage is implied by the name and the phrase 'for an asset', but the description never states when to prefer this over list_asset_tags, list_asset_collection_assets, or set_asset_tags_for_asset, nor does it give prerequisites. The empty-list edge case is behavioral, not routing guidance.

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

list_requests_by_endpointList requests by endpoint(s)A

Read-onlyIdempotent

Lists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs).

Authentication: Requires API key (user or enterprise).

Filters:

Time range via start / end. If start is omitted, defaults to the last 24 hours — unless request_id is provided, in which case the default start bound is widened to 90 days.
Status (success, error, user_error)
Request ID
Pagination via cursor/limit (limit defaults to 50, max 100)

Sorting:

By end time (default) or duration

Expansions:

Include payloads by adding expand=payloads

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
`limit`	No	Number of items to return per page (max 100)
`start`	No	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
`cursor`	No	Pagination cursor encoding the page number
`expand`	No	Fields to expand in the response. Use payloads to include input and output payloads.
`status`	No	Filter by request status
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`sort_by`	No	Sort results by end time or duration	ended_at
`request_id`	No	Filter by specific request ID
`endpoint_id`	Yes	Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely new context: API-key authentication is required, the default 24-hour window is widened to 90 days when request_id is supplied, and pagination limits are 50/100. It does not describe the response shape, which is a minor residual gap.

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 the purpose, then organized under bolded Authentication/Filters/Sorting/Expansions headings so an agent can scan it quickly. Slight redundancy: the limit default of 50 and max of 100 is restated from the schema's own description.

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 10-parameter read-only list tool with full schema coverage, annotations, and no output schema, the description covers auth, filtering, defaults, sorting, and expansion. Only the returned item structure is unaddressed, which is a minor omission given the tool is a conventional paginated list.

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 100%, so the schema already documents every parameter and baseline is 3. The description goes beyond it by explaining the conditional default on start (24h, or 90 days when request_id is present), the sort options, and the expand=payloads mechanism — interactions the schema does not capture.

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 and resource ('Lists requests') scoped to 'one or more endpoints', which is a meaningful narrowing versus the generic sibling search_requests. It does not explicitly name search_requests or say how the two differ, so the agent must infer the distinction from the endpoint_id requirement.

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 establishes when the tool applies (per-endpoint request retrieval) and cross-references 'usage/explore' for the endpoint_id syntax, but never states when to prefer it over search_requests or any exclusion. Usage is implied by the required endpoint_id rather than stated.

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

list_workflowsList user workflowsA

Read-onlyIdempotent

List workflows for the authenticated user with optional search and filtering.

Features:

Paginated results with cursor-based pagination
Search by workflow name or title
Filter by model endpoints used in the workflow

Authentication: Required. Returns only workflows owned by the authenticated user.

Common Use Cases:

Display user's workflow library
Search for specific workflows
Find workflows using particular models

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`search`	No	Search by workflow name or title
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`used_endpoint_ids`	No	Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds value beyond that by disclosing the ownership scoping ('Returns only workflows owned by the authenticated user') and cursor-based pagination behavior, which the agent cannot read from the annotations.

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-loads the core purpose, then organizes the rest under labeled sections with no filler. There is mild redundancy between the Features and Common Use Cases bullets (search and endpoint filtering are essentially repeated), which keeps it from a 5.

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?

With 5 optional params fully described in the schema and read-only annotations, the description covers the essentials plus auth scoping and pagination. No output schema exists, so it need not explain return values, though it could have noted what a workflow record contains.

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 100%, so the schema already documents limit, cursor, search, account, and used_endpoint_ids. The description restates the search and endpoint-filter semantics but adds no format or syntax detail beyond what the schema provides, so the baseline of 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+resource ('List workflows') and scopes it to the authenticated user, which distinguishes it from collection-wide listers. It does not explicitly name its closest sibling get_workflow or otherwise call out the single-vs-many distinction, so it falls short of a 5.

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 'Common Use Cases' section gives implied usage (displaying a library, searching, finding workflows by model), which is real guidance. However, it offers no explicit when-not conditions and never names the alternative tool (e.g., get_workflow for a single item), leaving the agent to infer routing.

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

move_asset_collectionMove asset collectionA

Destructive

Move a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries
`parent_collection_id`	No	Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle.

TDQS

A4/5.0

Behavior4/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 safety profile is covered. The description adds real domain behavior beyond that: only manual collections are movable, nesting is capped at 5 levels, and cycles are rejected. It omits that a confirm flag is required, though that is documented in the schema.

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?

Two tight sentences with the primary action first and the eligibility/limit constraints second. No filler, no restatement of the title.

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 destructive mutation with full annotation coverage and a fully documented 7-parameter schema, the description supplies the key domain constraints an agent needs. The absence of output schema is not an issue, though failure/partial-move semantics are left unstated.

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 100% and the parent_collection_id description already explains null-means-top-level plus the manual-collection/nesting/cycle rules. The description therefore restates schema content rather than adding new parameter meaning, making 3 the correct baseline.

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 (move) and resource (asset collection) plus the two destinations (under another collection or top level), which cleanly separates it from create/update/delete_asset_collection siblings. It does not name a sibling explicitly, but the action is unambiguous.

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?

The description states the applicable precondition clearly: only manual collections can be moved or act as folders, which functions as a when-not rule. It does not name update_asset_collection as the alternative for renaming/reparenting metadata, so the routing guidance is context-level rather than exhaustive.

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

preview_generation_batchReview ordered generation batchA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`tasks`	Yes	One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget.
`account`	No	Exact configured isolated API-key profile label.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description goes further by disclosing what the result hash binds (ordered inputs/lifecycle/store-IO/profile label/schemas/quotes) and the important caveat that unit pricing is neither final cost nor a spending cap. These are genuine behavioral details beyond the annotations.

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 tightly packed sentences with the core purpose front-loaded and zero filler. The telegraphic, jargon-dense style ('Hash binds ordered exact inputs/...') borders on cryptic but each clause carries load-bearing meaning.

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 preview/validation tool with no output schema, the description supplies the key behavioral facts an agent needs: it validates against current schemas, looks up unit pricing, and produces a hash over exact ordered inputs while performing no generation or writes. It is nearly complete, missing only explicit sibling routing.

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 100%, so the schema already documents tasks, model_id, input, store_io, lifecycle and account. The description restates the parameter concepts the hash binds (ordered inputs, lifecycle, store-IO, profile label) but adds no syntax or format detail beyond what the schema provides. 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 and resource: read-only schema validation plus native unit-pricing lookup for a batch of async jobs. The 'preview' framing (no generation, file write) is clear enough that an agent can tell it apart from submit_generation_batch, though the sibling is never named outright.

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 read-only/validation framing implies this is a dry-run to run before an actual submission, and the 'No generation, file write or key ownership validation' clause signals exclusions. However, it never explicitly says when to prefer this over submit_generation_batch or estimate_pricing, leaving the routing to inference.

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

remove_asset_from_collectionRemove asset from collectionA

Destructive

Remove an asset from a manual or character collection by request ID or vector ID.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered structurally. The description adds only the collection-type scope; it omits the mandatory confirm gate, idempotency key behavior, and reversibility of the removal, so it is a modest rather than rich contribution.

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?

A single sentence with the action and scope front-loaded and zero filler. Nothing needs trimming.

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?

This is a destructive mutation with 8 parameters, a nested payload, three mutually exclusive body input modes, and a required confirm flag, and there is no output schema. The description covers the core action but leaves the confirm requirement and body-input selection to the schema, which is adequate but thin for a destructive tool.

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 100%, so every parameter (account, confirm, payload, vector_id, request_id, payload_file, collection_id, Idempotency_Key) is already documented in the schema. The description echoes the two identifier options without adding format, precedence, or mutual-exclusivity detail, so the 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 and resource ('Remove an asset from ... collection') and narrows the applicable collection kinds to 'manual or character'. It does not explicitly contrast with the obvious sibling add_asset_to_collection, but the inverse relationship is unambiguous from the name.

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?

Implicit guidance only: naming 'manual or character collection' and 'request ID or vector ID' signals which collection kinds and identifier paths apply. There is no statement of prerequisites, when-not-to-use, or how this differs from add_asset_to_collection.

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

run_modelRun one model synchronouslyA

Destructive

ParametersJSON Schema

Name	Required	Description
`input`	Yes	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`store_io`	No	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate.
`lifecycle`	No	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds genuinely non-obvious context: this is a paid request, a synchronous timeout may leave an unknown paid outcome, and there is no retry or polling. That is meaningful beyond the annotations, though return/response behavior is only touched on.

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?

Four tight clauses, front-loaded with the core action and the paid/validation precondition. Every sentence carries signal (cost, validation, no defaults, timeout risk), though the telegraphic style is dense enough to require careful parsing.

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 paid, destructive, non-idempotent mutation with no output schema, the description covers cost, validation and timeout risk well. It does not clarify what a successful synchronous call returns (only what queue submissions return), leaving a real gap for a tool whose result the agent must act on.

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 100%, so the schema already documents model_id, input, confirm, account, store_io and lifecycle. The description reinforces 'Exact model_id/input required; do not invent fields or choose a default', which adds a little meaning but largely restates schema guidance — baseline 3 for full coverage is appropriate.

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?

The description states a specific verb+resource: it executes one paid model request synchronously ('Run one model synchronously'), and the contrast with queue submissions helps separate it from submit_job. However, it never names or distinguishes itself from the closely related generate_image / generate_video siblings, leaving the agent to infer the boundary.

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?

Usage is implied rather than stated: 'Queue submissions return receipt only' hints that this is the synchronous alternative, and 'No retry or polling' tells the agent not to wrap it in a polling loop. But no alternative (submit_job, submit_generation_batch) is named, and no explicit when-to-use / when-not condition is given.

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

search_modelsModel searchA

Read-onlyIdempotent

Unified endpoint for discovering model endpoints. Supports three usage modes:

1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata.

2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs.

3. Search Mode (search parameters): Filter models by free-text query, category, or status.

Expansion: Use expand to include additional data in each model object:

openapi-3.0 — full OpenAPI 3.0 schema in the openapi field
enterprise_status — enterprise readiness status (ready or pending) in the enterprise_status field

Examples of endpoint_id values:

fal-ai/flux/dev
fal-ai/wan/v2.2-a14b/text-to-video
fal-ai/minimax/video-01/image-to-video
fal-ai/hunyuan3d-v21

See fal.ai Model APIs for more details.

Authentication: Optional. Providing an API key grants higher rate limits.

Common Use Cases:

Browse available models for integration
Retrieve metadata for specific endpoints
Search for models by category or keywords
Get OpenAPI schemas for code generation
Build model selection interfaces

ParametersJSON Schema

Name	Required	Description
`q`	No	Free-text search query to filter models by name, description, or category
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`expand`	No	Fields to expand in the response. Supported values: 'openapi-3.0' (includes full OpenAPI 3.0 schema in 'openapi' field), 'enterprise_status' (includes enterprise readiness status)
`status`	No	Filter models by status - omit to include all statuses
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`category`	No	Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
`endpoint_id`	No	Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context: optional API key grants higher rate limits, and the expand parameter controls extra fields like full OpenAPI schema and enterprise status. It does not detail pagination behavior or complete response shape, which keeps it from a 5.

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?

The description is well-structured with bold section headers, front-loads the purpose, and progresses logically through modes, expansion, examples, authentication, and use cases. It is appropriately sized for a multi-mode tool, but the 'Common Use Cases' list largely echoes the already-stated modes, adding minor redundancy.

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?

Given the absence of an output schema, the description covers the main behaviors an agent needs: mode selection, expansion fields, authentication impact, and endpoint ID examples. It does not specify the exact response structure for List or Search modes beyond 'minimal metadata', leaving some return-value ambiguity, but it is otherwise complete for a search/discovery tool.

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 100%, so individual parameter meanings are already well documented. The description adds value by grouping parameters into the three usage modes, clarifying that endpoint_id can be combined with search params to narrow results, and explaining expand behavior with concrete field names. This adds combinatorial semantics beyond the schema, though it repeats some schema-level detail.

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?

The description states a specific resource ('model endpoints') and specifies three distinct usage modes (List, Find, Search) with clear parameter conditions. An agent can immediately tell this is a discovery/search endpoint for models, distinct from utility tools like get_pricing or get_usage.

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?

It explicitly maps parameter combinations to three usage modes and provides common use cases, which gives clear operational context. However, it does not name a sibling alternative such as get_model_info when the agent needs a single model's details, and no explicit 'when not to use' guidance is given.

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

search_requestsSearch RequestsA

Read-onlyIdempotent

Search, filter, and browse your request history. Supports three modes:

1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search.

2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first).

3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity.

Filter Options:

endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs)
exclude_api_requests / only_api_requests: Filter by request source

Examples:

Semantic text search: ?query=sunset+landscape
Image similarity: ?image_url=https://...&min_similarity=0.5
Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev
Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
`query`	No	Text search query for semantic search. Mutually exclusive with image_url and video_url.
`cursor`	No	Pagination cursor from previous response. Encodes the page number.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`endpoint`	No	Deprecated: use `endpoint_id`. Single-endpoint filter retained for backward compatibility. If both are provided, `endpoint_id` wins.
`image_url`	No	Image URL for similarity search. Mutually exclusive with query and video_url.
`video_url`	No	Video URL for similarity search. Mutually exclusive with query and image_url.
`endpoint_id`	No	Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs).
`min_similarity`	No	Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided.
`only_api_requests`	No	Only include requests made via API keys. Mutually exclusive with exclude_api_requests.
`exclude_api_requests`	No	Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests.

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that: result ordering (newest first) and the fact that filters narrow candidates before similarity ranking. It omits pagination cost/limits and response shape, keeping it below 5.

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?

Headers and numbered modes make it scannable and the core behavior is front-loaded. The examples section is somewhat redundant with the mode explanations and inflates length, preventing a 5.

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?

With 11 optional parameters and no output schema, the description covers mode selection, filter semantics, ordering, and combination rules well. It does not explain pagination behavior or the shape of returned results, which matters for a search tool the agent must iterate on.

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 coverage is 100%, so the baseline is 3, but the description goes further by demonstrating concrete parameter combinations (e.g., combining query with endpoint_id, min_similarity with image_url) that the schema does not illustrate. It adds working syntax, though the 'Filter Options' bullets largely restate the schema.

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?

The description states a specific verb and resource (search/filter/browse request history) and clearly enumerates three operating modes, which is more than most definitions offer. It stops short of a 5 because it never distinguishes itself from the sibling list_requests_by_endpoint, leaving the agent to infer which one to pick.

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?

It explicitly defines when each mode activates based on which parameters are supplied (query/image_url/video_url vs. none vs. both), which is genuine mode-selection guidance. However, it offers no when-not guidance and never routes to or away from sibling tools such as list_requests_by_endpoint.

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

set_asset_tags_for_assetSet tags for an assetB

Destructive

Set tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`tag_ids`	No	Full replacement set of tag IDs
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`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

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds a genuinely non-obvious side effect: unresolved request/vector references are materialized into assets before tag state is written, meaning this call can create an asset. That is real behavioral value beyond the annotations, though it stops short of stating reversibility or failure behavior.

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?

Two short sentences, purpose front-loaded, with the input requirement and side effect packed into the second. The phrase 'tag state is added' is slightly opaque for what the schema calls a 'full replacement set,' costing it the top score.

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 an 8-parameter mutation with nested payload and no output schema, the description covers the core action and the materialization side effect, and annotations carry the safety profile. It still leaves the replacement-vs-incremental semantics ambiguous ('added' vs schema's 'Full replacement set') and gives no guidance against the sibling assign/unassign tools.

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 100%, so the schema already explains tag_ids, vector_id, request_id, confirm, account, payload and idempotency key. The description only echoes the request/vector ID option and adds no syntax, exclusivity, or defaulting detail beyond what the schema provides, so the 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?

Names a specific verb and resource (set tags on an asset) and is unambiguous about the target. It does not, however, differentiate itself from the closely related siblings assign_asset_tag and unassign_asset_tag, so an agent cannot tell from the text alone which tagging verb to pick.

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

Usage Guidelines2/5

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

The only guidance is 'Provide a request ID or vector ID,' which is an input hint rather than a when-to-use rule. There is no statement about when to prefer this over assign_asset_tag/unassign_asset_tag, nor any prerequisite such as the confirm flag the schema requires for mutations.

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

set_storage_file_aclSet file ACLA

Destructive

Replaces the Access Control List of a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide.

Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent.

Authentication: Required. The API key must have the assets:write permission.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters.
`rules`	No	User-specific overrides to the default decision
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`default`	No	Fallback decision when no user-specific rule matches
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.

TDQS

A4.1/5.0

Behavior4/5

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

Goes well beyond the annotations (which already cover destructive/read-only/idempotent/open-world) by disclosing the auth requirement ('assets:write' permission), the subtle dropping of rules referencing nonexistent users, and the need to verify the returned ACL. These are genuinely useful mutation behaviors not derivable from the hints.

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?

Reasonably sized and front-loaded with the core action; each sentence carries substantive information. Slightly verbose with the formatting/bold auth line, but nothing is filler.

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 destructive, open-world mutation tool with no output schema, the description covers auth requirements, ACL semantics, edge-case behavior (dropped rules), and response verification. It leaves the `account`/`confirm`/`payload` body-variant parameters to the schema, which is acceptable given full schema coverage.

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 coverage is 100%, so baseline is 3; the description rises above it by explaining the semantic consequence of the `default` enum values ('allow' with no rules makes the file public; 'forbid'/'hide' restricts) and the dropped-rule behavior for user rules. It adds meaning beyond the raw schema text.

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 ('Replaces the Access Control List of a fal CDN file'), which cleanly distinguishes it from the read-only sibling get_storage_file_acl. An agent knows exactly what this tool mutates without opening the schema.

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 establishes the tool's purpose and effects ('makes the file public', 'restricts it to the rules you provide'), which implies when to use it, but it never explicitly states when to choose this over get_storage_file_acl or other storage tools. Usage is left to inference.

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

sign_storage_file_urlSign file URLA

Destructive

Creates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files.

The signature is valid for expiration_seconds (up to 7 days).

Authentication: Required. The API key must have the assets:read permission.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters.
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`output_file`	Yes	Required absolute new owner-private file; signed credential URL is never echoed.
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`expiration_seconds`	No	How long the signed URL stays valid, in seconds (max 7 days)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare the write/destructive, non-idempotent, open-world profile, so the bar is lower. The description still adds real value: the ACL bypass behavior, the 7-day TTL ceiling, and the explicit `assets:read` permission requirement. It does not, however, note that the signed URL is written to a file rather than returned.

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?

Three short, front-loaded sentences: purpose first, use case second, constraints/auth last. No filler, every sentence earns its place.

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 7-parameter tool with a nested payload object, mutually exclusive body inputs, a required output_file, and no output schema, the description covers only purpose, TTL, and auth. It never explains where the signed URL goes or how the payload/payload_file/flat-flag union works, leaving the schema to carry those semantics.

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 100%, so the schema already documents all 7 parameters including expiration_seconds' max. The description's 'valid for expiration_seconds (up to 7 days)' merely restates the schema, adding no new format or constraint meaning.

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?

The description states a specific verb+resource ('Creates a signed URL that grants temporary access to a fal CDN file') and adds a distinguishing capability ('regardless of its ACL'). This clearly separates it from ACL-management siblings like get_storage_file_acl / set_storage_file_acl, though it never names an alternative explicitly.

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?

'Useful for sharing access-restricted files' gives one implied use case but no when-not conditions, prerequisites, or named alternatives. The agent can infer usage but must reason about it rather than being told.

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

submit_generation_batchSubmit exact reviewed generation batchA

Destructive

ParametersJSON Schema

Name	Required	Description
`tasks`	Yes	One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget.
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`review_sha256`	Yes

TDQS

A4.2/5.0

Behavior5/5

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

Discloses behavior well beyond the annotations: sequential submission, stop-on-first-failure, what is reported (known request IDs, failed and unattempted indices), and critically what is NOT provided (no polling, retries, rollback, continuation, or budget guarantee). The destructiveHint/openWorldHint annotations are consistent with this and the description adds the operational failure model an agent needs before committing paid work.

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 the action and the guardrail before the failure model, and no sentence is filler. The telegraphic, semicolon-heavy phrasing packs a lot into two sentences at some cost to readability.

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 destructive, non-idempotent paid submission with no output schema, the description covers the essential contract: validation gate, sequencing, failure handling, and result reporting. Remaining gaps are minor, such as what a successful response contains beyond request IDs.

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 coverage is 75% and the description adds meaning on top: tasks are ordered 1-10 and explicitly 'not a cost or output-count budget', and review_sha256 is tied to the refuse-if-changed validation gate. It does not explain the account or confirm parameters, which the schema handles only thinly.

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 and resource ('Confirmed one-to-ten async jobs', 'paid submission') and the batch nature is unambiguous. It does not explicitly name the sibling preview_generation_batch or contrast itself with submit_job, so the agent must infer the review-then-submit relationship from 'Confirmed' and 'refuse changed hash'.

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 a clear precondition chain: refetch current schemas and unit quotes, validate all, refuse changed hash, and only then make the first paid submission. This is strong when-to-use guidance, but no alternative tool is named and there is no explicit 'do not use this for previewing' exclusion.

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

submit_jobSubmit one queued jobA

Destructive

ParametersJSON Schema

Name	Required	Description
`input`	Yes	Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters.
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`model_id`	Yes	Exact current catalog endpoint ID. Never guess model names or parameter mappings.
`store_io`	No	Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate.
`lifecycle`	No	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already flag destructive=false... rather destructive=true, non-idempotent, open-world. The description adds material context beyond them: this is a paid operation, queue submissions return only a receipt, a synchronous timeout can leave an unknown paid outcome, and there is no retry/polling. This financial/partial-failure disclosure is genuinely valuable.

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?

Four dense sentences with the core action front-loaded and no filler; each sentence carries a distinct constraint (exactness, receipt-only, timeout risk, no retry). Slightly terse phrasing borders on cryptic but is efficient.

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 destructive, paid, non-idempotent mutation tool with a rich nested schema and no output schema, the description covers the key risks (cost, receipt-only return, unknown outcome) an agent needs. It omits how to retrieve results (get_job_status) beyond stating no polling, leaving a small gap.

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 100%, so all six parameters are already documented with meaning (e.g. confirm, store_io, lifecycle ACL). The description reinforces that model_id/input must be exact rather than guessed, but adds no syntax or mapping detail beyond the schema, so 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+resource: submitting a confirmed paid model request that has passed native input-schema validation, requiring exact model_id/input. It reads as a single-job submission distinct from batch/asset siblings, but never names run_model, generate_image, or submit_generation_batch, so the agent is not explicitly routed away from look-alike siblings.

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?

Adds constraints (exact model_id/input, no invented fields, no default selection) and warnings (receipt-only on queue, unknown paid outcome on timeout, no retry/polling), which imply how it should be used. However, it never states when to choose this over run_model or generate_image/video, or that get_job_status is the follow-up for results.

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

unassign_asset_tagUnassign tag from assetC

Destructive

Unassign a tag from an asset by request ID or vector ID.

ParametersJSON Schema

Name	Required	Description
`tag_id`	Yes	Tag ID
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`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

TDQS

C2.7/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing behavioral beyond that — it never mentions the confirm=true requirement, irreversibility, or account scoping that the schema fields imply are needed.

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?

A single front-loaded sentence with no wasted words, which is appropriate for this operation. It is efficient, though the misleading identifier clause costs it a point.

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

Completeness2/5

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

For a destructive, non-idempotent mutation with no output schema, the description omits the confirm requirement, account scoping, and any note on reversibility. The annotations cover the destructive profile, but an agent still lacks enough context to invoke this safely.

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

Parameters2/5

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

Schema coverage is 100%, so the baseline is 3, but the description's phrase 'by request ID or vector ID' implies those are the identifying inputs when the schema's only required parameter is tag_id and the ID fields are described as pre-mutation asset-saving inputs. This adds confusion rather than clarity beyond the schema.

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?

The description names a specific verb and resource ('Unassign a tag from an asset'), which cleanly distinguishes it from the sibling assign_asset_tag and set_asset_tags_for_asset. The trailing 'by request ID or vector ID' muddies rather than sharpens the purpose, since those identifiers are not the required input.

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

Usage Guidelines2/5

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

There is no explicit guidance on when to use this versus assign_asset_tag, set_asset_tags_for_asset, or delete_asset_tag. Removal is only implied by the verb, and no prerequisites or conditions are stated.

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

unfavorite_assetUnfavorite assetC

Destructive

Unfavorite an asset by request ID or vector ID.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`vector_id`	No	Vector ID to save as an asset before mutating
`request_id`	No	Request ID to save as an asset before mutating
`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

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds nothing beyond them: no statement of what is removed, whether it is reversible, whether confirm is needed, or how retries behave despite an Idempotency_Key parameter existing.

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?

A single short sentence with the action front-loaded and zero filler. Nothing redundant or padded.

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

Completeness2/5

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

For a destructive, non-idempotent mutation with 7 parameters, a nested payload object, four overlapping body-input paths (flat flags, payload, payload_file) and no output schema, the description is far too thin. It does not explain the mutually exclusive body forms, the confirm gate, or idempotency behavior.

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 100%, so every parameter is already documented in the schema and the baseline is 3. The description echoes the two ID parameters but adds no syntax, precedence rule for request_id vs vector_id, or interaction with the nested payload.

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 and resource (unfavorite an asset) plus the two acceptable identifiers (request ID or vector ID), which pins the target precisely. It differentiates implicitly from unfavorite_asset_collection and unfavorite_asset_character by saying 'asset', though it never names them or its inverse favorite_asset.

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

Usage Guidelines2/5

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

No when-to-use guidance, no prerequisites, and no mention of the alternative favorite_asset or the collection/character variants. It also omits the fact that the mutation requires confirm=true, which is only discoverable by reading the schema.

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

unfavorite_asset_characterUnfavorite asset characterB

Destructive

Unfavorite an asset character for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`character_id`	Yes	Character collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.1/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond the name—no mention of the mandatory confirm=true requirement, irreversibility, or idempotency behavior, which would have been valuable for a mutation tool.

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?

A single front-loaded sentence with zero wasted words; it states the action and scope immediately.

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?

Annotations cover the destructive/idempotent profile and the schema is fully documented, so the description is minimally sufficient. However, for a mutation requiring confirm=true, the description omits the critical caveat that the operation will not proceed without it.

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 100%, so the schema already documents all four parameters including account, confirm, and Idempotency_Key. The description adds no parameter-level meaning, so the baseline 3 is appropriate.

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?

The description states a specific verb ('Unfavorite') and resource ('asset character') scoped to the authenticated user's fal Assets library. It is clearly distinct from favorite_asset_character by name, though it does not explicitly route the agent between the two.

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

Usage Guidelines2/5

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

There is no guidance on when to use this versus favorite_asset_character or other character tools, and no mention of prerequisites such as the required confirm flag. The agent must infer usage entirely from the name.

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

unfavorite_asset_collectionUnfavorite asset collectionB

Destructive

Unfavorite an asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds only the scoping fact that it applies to the authenticated user's library; it says nothing about the required 'confirm' gate or what an unfavorite actually removes/retains.

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?

A single front-loaded sentence with the action and scope, no filler and no repetition of the title. Nothing could be trimmed without losing information.

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 one-required-parameter mutation with full schema coverage, rich annotations, and no output schema, the description is close to sufficient. It stops short of explaining the confirm-gate behavior or the consequences of the destructive flag, which would be the remaining value-add.

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 100%, so all four parameters (including the non-obvious 'confirm' and 'Idempotency_Key') are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so 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+resource ('Unfavorite an asset collection') and adds scope ('authenticated user's fal Assets library'), making it clearly distinct from favorite_asset_collection and delete_asset_collection. It does not explicitly name the sibling alternative, but the verb is unambiguous.

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

Usage Guidelines2/5

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

No when-to-use, when-not-to-use, or alternative is given. The existence of favorite_asset_collection as the inverse operation is left for the agent to infer, and there is no guidance on prerequisites or reversibility.

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

update_asset_characterUpdate asset characterA

Destructive

ParametersJSON 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	Must be true for the requested mutation, paid work or private output file.
`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	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.

TDQS

A3.6/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 safety profile is covered. The description adds one non-obvious behavior — unresolved ID references are materialized before character state is added — which hints at a side effect beyond annotations. It still does not disclose the confirm requirement, permission needs, or reversibility of the mutation.

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 compact sentences with the resource and scope front-loaded, then the reference-image preference, then the materialization note. Every sentence is relevant, though the first sentence partly restates the title.

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 10-parameter mutation tool with a nested payload object, no output schema, and fully documented parameters, the description covers purpose, image-reference format, and one behavioral side effect. The remaining rules (mutually exclusive body forms, confirm flag) are fully specified in the schema, so nothing critical is missing.

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 100%, so the schema already documents all ten parameters thoroughly. The description's reference_images guidance duplicates the schema's own parameter text verbatim, adding no new meaning beyond it. Baseline 3 is appropriate when the schema carries the load.

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 and resource ('Update an asset character') plus the scope ('authenticated user's fal Assets library'), which lets an agent distinguish it from create_asset_character and delete_asset_character. It is clear but never restates the required character_id target role or contrasts against those siblings explicitly.

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?

Offers real guidance for one field ('Prefer vector IDs or request IDs in reference_images... use fal-hosted image URLs only for standalone images'), which is genuine when-to-use advice. However, there is no guidance on when to update vs. create/delete a character, no mention of when the confirm flag is needed, and no exclusions for the alternative body forms (payload vs. flat flags).

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

update_asset_collectionUpdate asset collectionC

Destructive

Update asset collection for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`icon`	No	Optional collection icon
`name`	No	Collection display name
`color`	No	Optional collection color
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`filters`	No	Assets filter DSL
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`description`	No	Optional collection description
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`collection_id`	Yes	Collection ID
`Idempotency_Key`	No	Optional idempotency key for safe request retries
`cover_image_url`	No	Optional fal-hosted cover image URL for the collection

TDQS

C2.8/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds no behavioral context beyond that — no mention of the destructive overwrite semantics, the requirement to set confirm=true, or the idempotency key for retries, all of which matter for a mutation.

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

Conciseness3/5

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

It is a single short sentence with zero waste, which is structurally fine and front-loaded. But the brevity comes at the cost of under-specification rather than being a tight summary, so it is merely adequate.

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

Completeness2/5

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

For a 12-parameter mutation tool with a nested/union body, a confirm flag, and an idempotency key, the description omits the mutually exclusive body-input modes and the confirm requirement. Annotations cover the safety hints, but the invocation-relevant complexity is left entirely to the schema.

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 100%, so the baseline is 3; the description adds no parameter-level meaning beyond what the schema already documents. The genuinely tricky union of flat flags vs. payload vs. payload_file is described only in the schema, not the description, so nothing extra is contributed.

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 and resource ('Update asset collection') scoped to the authenticated user's fal Assets library, which is clearer than a tautology. However it does not say what can be changed (name, color, icon, description, cover image, filters) nor distinguish itself from same-resource siblings like move_asset_collection, favorite_asset_collection, or update_asset_tag.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Nothing explains how it differs from move_asset_collection, favorite_asset_collection, or the create/get/delete collection siblings, and no prerequisites or exclusions are stated.

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

update_asset_tagUpdate asset tagC

Destructive

Update asset tag for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`name`	No	Tag name
`tag_id`	Yes	Tag ID
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`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

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is fully covered structurally. The description adds no behavioral context beyond them — it never mentions the mandatory confirm flag, what an update destroys or overwrites, or idempotency/retry semantics, despite idempotentHint=false.

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?

A single efficient sentence with no filler. It is appropriately sized, though it is so short that the front-loaded content is the only content.

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 destructive mutation with a nested body, a confirm gate, and no output schema, the description omits any mention of the confirmation requirement, the result of a successful update, or the payload/payload_file exclusivity rules. Annotations and the rich schema compensate for most of this, leaving the definition merely adequate.

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 100% and all 7 parameters (including the nested payload, payload_file mutual exclusivity, account, confirm, and Idempotency_Key) are documented in the schema. The description adds no parameter meaning at all, so the 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 tag) scoped to the authenticated user's fal Assets library. It is clear enough to distinguish from create_asset_tag/delete_asset_tag by name, but it never explicitly differentiates itself from the closely related set_asset_tags_for_asset, assign_asset_tag, or unassign_asset_tag siblings.

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

Usage Guidelines2/5

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

The description offers no when-to-use guidance, no prerequisites, and no mention of alternatives such as set_asset_tags_for_asset or assign_asset_tag. The agent must infer the selection criteria from the tool name alone.

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

update_storage_settingsUpdate storage settingsA

Destructive

ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent.

These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests.

Authentication: Required. The API key must have the account:settings:write permission.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`initial_acl`	No	Default ACL applied to newly uploaded files. Null uses the system default (public).
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`expiration_duration_seconds`	No	Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration.

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare destructive and non-idempotent, and the description adds real depth on top: replace-not-merge semantics, null-clears-fields behavior, silent dropping of ACL rules for nonexistent users, and the fact the response reflects what was actually saved. It also states the required permission (account:settings:write), which annotations cannot express.

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 core action, then layers replace semantics, ACL caveats, header relationship, and authentication – each sentence earning its place. No filler or restatement of the title.

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 a complex nested union body and no output schema, the description supplies the missing pieces: destructive replace behavior, auth/permission requirement, override relationship to the request header, and a hint about verifying the returned settings. Nothing an agent needs to call it correctly is absent.

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 coverage is 100%, so the schema already documents each field including null semantics, giving a baseline of 3. The description adds value beyond that by explaining the union-body replace contract ('always send the full desired configuration') and warning that saved rules may differ from those sent – semantics the per-property schema does not convey.

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 precise verb (replaces) and resource (account-level storage lifecycle settings) with scope narrowed to newly uploaded fal CDN files. This cleanly distinguishes it from the sibling get_storage_settings (read) and set_storage_file_acl (per-file, not account-level) without opening either schema.

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 clear operational guidance – 'always send the full desired configuration' because omitted/null fields reset to defaults – and notes the per-request header that overrides these same settings. It stops short of naming a sibling tool or an explicit when-not condition, so it is strong context rather than full alternate-tool routing.

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

upload_assetUpload assetB

Destructive

Upload asset for the authenticated user's fal Assets library.

ParametersJSON Schema

Name	Required	Description
`url`	No	fal-hosted media URL to ingest into the asset library
`type`	No	Media type for the uploaded asset
`prompt`	No	Optional caller-provided caption or description to index with the uploaded asset
`account`	No	Exact private account key profile label, not an authenticated provider owner ID.
`confirm`	No	Must be true for the requested mutation, paid work or private output file.
`payload`	No	Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
`tag_ids`	No	Tag IDs to assign to the uploaded asset
`favorite`	No	Whether to favorite the uploaded asset immediately
`payload_file`	No	Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.
`collection_id`	No	Optional manual collection ID to add the uploaded asset to
`Idempotency_Key`	No	Optional idempotency key for safe request retries

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description's burden is reduced. It adds a genuine but small piece of context: the target scope is the authenticated user's own library. It says nothing about the confirm flag, retries, or what the destructive behavior entails.

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?

A single front-loaded sentence with no wasted words, and the destination scope is stated up front. It is concise, though arguably concise at the expense of the detail this tool's complexity demands.

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

Completeness2/5

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

With 11 parameters, a nested payload object, union body inputs, and no output schema, a one-sentence description is materially incomplete. It never addresses the required confirm=true gate, the payload/payload_file exclusivity rule, or idempotency handling – all of which an agent needs to invoke this mutation 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 description coverage is 100%, so every one of the 11 parameters is already documented in the schema, giving a baseline of 3. The description contributes no additional parameter meaning, syntax, or interaction rules (e.g., payload vs flat-body mutual exclusivity) beyond what the schema states.

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 and resource ('Upload asset') plus a destination ('fal Assets library'), so the agent knows what the tool does. It does not distinguish itself from the sibling upload_file or from add_asset_to_collection, leaving the asset-vs-file boundary to inference.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent cannot tell from this text whether to prefer upload_asset over upload_file or add_asset_to_collection for a given input.

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

upload_fileUpload one local input fileB

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured isolated API-key profile label.
`confirm`	No	Explicit approval for the requested paid work, mutation, upload or private file.
`file_path`	Yes	Absolute selected local media file, regular/non-symlink, 1 byte–20 MiB.
`lifecycle`	No	Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider.
`content_type`	Yes	Plain MIME type matching the selected media.

TDQS

B3/5.0

Behavior4/5

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

Annotations already declare the mutation/destructive/open-world profile, so the bar is lower. The description nonetheless adds real behavioral context beyond the schema: the upload-initiation protocol, a credential-free HTTPS PUT, and redirects being refused. It stops short of stating auth requirements or retry/failure behavior for the caller.

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

Conciseness3/5

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

It is compact at two sentences with no filler, but it is front-loaded with a verbless constraint fragment instead of the action, and the telegraphic style ('Confirmed selected...', 'credential-free... with redirects refused') reads as compressed internal notes rather than a purpose-first statement.

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 destructive, non-idempotent mutation with five parameters, a nested ACL/expiration object, and no output schema, the description covers the transport mechanism and file limits but says nothing about the lifecycle/ACL parameters, the confirm requirement, or any return indication. Adequate but with clear gaps for the tool's complexity.

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 100%, so the schema already documents all five parameters including the nested lifecycle/ACL object. The description largely restates the file_path constraints (absolute, regular, non-symlink, 1 byte–20 MiB) rather than adding syntax or semantics beyond the schema, so the baseline 3 is appropriate.

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

Purpose3/5

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

The title names a clear verb+resource ('Upload one local input file'), and the description implies the upload target ('HTTPS fal.media PUT') plus explicit scope limits (no remote URL, no base64, no auto-generation). However, the opening is a verbless noun fragment ('Confirmed selected absolute regular non-symlink local file'), and the sibling upload_asset is never referenced, so the agent cannot easily tell the two apart.

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

Usage Guidelines2/5

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

The description lists what it will NOT do (no remote URL ingestion, no base64 output, no multipart retries), which is exclusionary input guidance rather than when-to-use routing. There is no mention of alternatives such as upload_asset, nor any condition telling the agent when this tool is the right choice.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

66 tool updatesv2.0.0Oct 3, 2026
- First observedadd_asset_to_collection
- First observedassign_asset_tag
- First observedcancel_job
- First observedcreate_asset_character
- First observedcreate_asset_collection
- First observedcreate_asset_tag
- First observedcreate_workflow
- First observeddelete_asset_character
- First observeddelete_asset_collection
- First observeddelete_asset_tag
- First observeddelete_request_payloads
- First observedestimate_pricing
- First observedfavorite_asset
- First observedfavorite_asset_character
- First observedfavorite_asset_collection
- First observedgenerate_image
- First observedgenerate_video
- First observedget_account_billing
- First observedget_analytics
- First observedget_asset
- First observedget_asset_character
- First observedget_asset_collection
- First observedget_asset_collection_hierarchy
- First observedget_asset_lineage
- First observedget_billing_events
- First observedget_job_result
- First observedget_job_status
- First observedget_model_info
- First observedget_operation_schema
- First observedget_organization_teams
- First observedget_organization_usage
- First observedget_pricing
- First observedget_storage_file_acl
- First observedget_storage_settings
- First observedget_usage
- First observedget_workflow
- First observedlist_accounts
- First observedlist_asset_characters
- First observedlist_asset_collection_assets
- First observedlist_asset_collections
- First observedlist_asset_tags
- First observedlist_asset_tags_for_asset
- First observedlist_assets
- First observedlist_requests_by_endpoint
- First observedlist_workflows
- First observedmove_asset_collection
- First observedpreview_generation_batch
- First observedremove_asset_from_collection
- First observedrun_model
- First observedsearch_models
- First observedsearch_requests
- First observedset_asset_tags_for_asset
- First observedset_storage_file_acl
- First observedsign_storage_file_url
- First observedsubmit_generation_batch
- First observedsubmit_job
- First observedunassign_asset_tag
- First observedunfavorite_asset
- First observedunfavorite_asset_character
- First observedunfavorite_asset_collection
- First observedupdate_asset_character
- First observedupdate_asset_collection
- First observedupdate_asset_tag
- First observedupdate_storage_settings
- First observedupload_asset
- First observedupload_file

Deploy Server

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

TDQS

B3.1/5.0

Scored 2026-10-03 06:40 across 66 tools

Disambiguation2/5

Several tools have overlapping or identical purposes: run_model, submit_job, generate_image, and generate_video all share the exact same description, making it impossible to distinguish when to use which. search_requests and list_requests_by_endpoint also overlap heavily, and list_assets vs list_asset_collection_assets vs get_asset cover similar ground.

Naming Consistency4/5

Most tools follow a consistent verb_noun snake_case pattern (get_model_info, create_workflow, delete_asset_collection). A few deviations like assign_asset_tag/unassign_asset_tag vs set_asset_tags_for_asset add minor inconsistency but the overall scheme is predictable.

Tool Count2/5

66 tools is far too many for coherent agent use; the set is bloated with many near-duplicate CRUD operations for assets, collections, characters, and tags. This volume forces significant disambiguation burden on the caller.

Completeness3/5

The surface covers many domains (models, pricing, usage, analytics, billing, workflows, assets, storage, jobs) with reasonable CRUD completeness for assets and collections. However, clear gaps exist: no list_workflows deletion/update, no search_assets tool despite list_assets mentioning semantic search, and no clear way to poll/cancel batch jobs beyond the single cancel_job.

Maintenance

ActivityNo data

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

ModelsLab Agent Control Plane A
io.github.ModelsLab
Account, billing, team, API key and model discovery tools for agents that use ModelsLab.
AI & Machine Learning Payments & Billing Security
101
MorphedOAuth
app.morphed
Create AI images and videos, manage projects and credits, and use workspace campaign context.
AI & Machine Learning Image & Video Processing
1
Prompeteer AOAuth
ai.prompeteer
Generate contextual prompts and reusable agent skills, evaluate prompts with the 16-dimension Prompt Score, and manage saved work in PromptDrive. Twelve MCP tools also provide authorized access to private Memory for source-grounded answers. Connect over Streamable HTTP using OAuth 2.1 and PKCE. Generation consumes account quota and automatically saves successful results; Memory access follows account permissions and plan limits.
App Automation Developer Tools Product Management
123
APICK AI A
app.apick
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
AI & Machine Learning Image & Video Processing
1511

Related MCP Servers

Fal.ai MCP Server
Image & Video Processing App Automation Multimedia Processing
gravicity-archive
A
license
B
quality
F
maintenance
Enables seamless integration with Fal.ai's 600+ image generation models including Flux and Stable Diffusion. Supports real-time streaming, workflow execution, and unified access to AI image generation through natural language.
Updated a year ago (2025-09-08 03:46 UTC)
5
18 npm
MIT
fal.ai MCP Server
AI & Machine Learning Search Developer Tools
derekalia
A
license
A
quality
D
maintenance
Enables discovery, search, generation, and management of AI models via fal.ai, allowing Claude Desktop and other MCP clients to interact with fal.ai services.
Updated a year ago (2025-10-31 00:55 UTC)
12
329 npm
MIT
APIAny MCP
ailingqu
-
license
Not graded
quality
Not graded
maintenance
Enables discovery of public AI models with pricing, documentation context, and OpenAI-compatible integration examples. Supports both read-only queries and paid async media generation tasks.
Updated 3 months ago (2026-06-23 12:14 UTC)
-
fal
AI & Machine Learning Image & Video Processing
MalcolmXavier7
A
license
A
quality
B
maintenance
Enables MCP clients to run 600+ generative AI models from fal.ai, including image, video, audio, and text, with tools for synchronous and asynchronous execution, model catalog browsing, and schema inspection.
Updated 2 months ago (2026-07-28 01:38 UTC)
8
1
MIT

fal.ai MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up fal.ai access

Private account access

Official account connections

Costs and permissions

Data and file controls

Rotation and revocation

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

search_models

get_pricing

estimate_pricing

get_usage

get_analytics

get_billing_events

delete_request_payloads

list_requests_by_endpoint

search_requests

list_workflows

create_workflow

get_workflow

list_assets

list_asset_collections

create_asset_collection

get_asset_collection

update_asset_collection

delete_asset_collection

get_asset_collection_hierarchy

favorite_asset_collection

unfavorite_asset_collection

move_asset_collection

list_asset_collection_assets

add_asset_to_collection

remove_asset_from_collection

list_asset_characters

create_asset_character

update_asset_character

get_asset_character

delete_asset_character

favorite_asset_character

unfavorite_asset_character

list_asset_tags

create_asset_tag

set_asset_tags_for_asset

update_asset_tag

delete_asset_tag

upload_asset

get_asset

get_asset_lineage

favorite_asset

unfavorite_asset

list_asset_tags_for_asset

assign_asset_tag

unassign_asset_tag

get_storage_file_acl

set_storage_file_acl

sign_storage_file_url

get_storage_settings

update_storage_settings

get_account_billing

get_organization_teams

get_organization_usage

get_model_info

run_model

submit_job

generate_image

generate_video

get_job_status

get_job_result

`search_models`

`get_pricing`

`estimate_pricing`

`get_usage`

`get_analytics`

`get_billing_events`

`delete_request_payloads`

`list_requests_by_endpoint`

`search_requests`

`list_workflows`

`create_workflow`

`get_workflow`

`list_assets`

`list_asset_collections`

`create_asset_collection`

`get_asset_collection`

`update_asset_collection`

`delete_asset_collection`

`get_asset_collection_hierarchy`

`favorite_asset_collection`

`unfavorite_asset_collection`

`move_asset_collection`

`list_asset_collection_assets`

`add_asset_to_collection`

`remove_asset_from_collection`

`list_asset_characters`

`create_asset_character`

`update_asset_character`

`get_asset_character`

`delete_asset_character`

`favorite_asset_character`

`unfavorite_asset_character`

`list_asset_tags`

`create_asset_tag`

`set_asset_tags_for_asset`

`update_asset_tag`

`delete_asset_tag`

`upload_asset`

`get_asset`

`get_asset_lineage`

`favorite_asset`

`unfavorite_asset`

`list_asset_tags_for_asset`

`assign_asset_tag`

`unassign_asset_tag`

`get_storage_file_acl`

`set_storage_file_acl`

`sign_storage_file_url`

`get_storage_settings`

`update_storage_settings`

`get_account_billing`

`get_organization_teams`

`get_organization_usage`

`get_model_info`

`run_model`

`submit_job`

`generate_image`

`generate_video`

`get_job_status`

`get_job_result`

`cancel_job`

`upload_file`

`list_accounts`

`get_operation_schema`

`preview_generation_batch`

`submit_generation_batch`

Native `search_models`: GET /models

Native `get_pricing`: GET /models/pricing

Native `estimate_pricing`: POST /models/pricing/estimate

Native `get_usage`: GET /models/usage

Native `get_analytics`: GET /models/analytics

Native `get_billing_events`: GET /models/billing-events

Native `delete_request_payloads`: DELETE /models/requests/{request_id}/payloads

Native `list_requests_by_endpoint`: GET /models/requests/by-endpoint

Native `search_requests`: GET /models/requests/search

Native `list_workflows`: GET /workflows

Native `create_workflow`: POST /workflows

Native `get_workflow`: GET /workflows/{username}/{workflow_name}

Native `list_assets`: GET /assets

Native `list_asset_collections`: GET /assets/collections