The fal.ai MCP server exposes 66 tools for fal.ai model discovery, pricing, generation, queue management, and account/asset/storage operations via CLI or MCP.
Discover and inspect models: search current catalog, retrieve exact IDs, schemas, metadata, and category/status filters.
Estimate and review costs: get unit pricing, estimate via historical/unit methods, inspect usage, analytics, billing events, and account credits.
Generate media: confirmed paid runs or queued jobs for image/video/other models using exact native schemas, with receipts and status/result/cancel reads.
Batch review and submit: preview 1–10 ordered generation tasks with schema/price hash, then submit exact reviewed batch with stop-on-failure reporting.
Manage Assets: list/search assets, collections (nested, favorite, move), characters, tags, lineage, and add/remove/favorite/set tags.
Control storage/CDN: read/set file ACLs, sign temporary URLs to private files, get/update account storage lifecycle settings.
Manage workflows: list, create, get user workflows with contents and endpoint filters.
Upload local files: confirmed upload of 1 byte–20 MiB regular local files to fal CDN.
Account and organization visibility: list private account profiles, get billing, organization teams and organization usage.
Inspect native operations: get local method/path/query/header/body schemas without provider calls.
Safety: reads are non-mutating; 34 confirmed operations require explicit confirmation, with read-only/destructive environment controls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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 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. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. 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.
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 --agentRegister the local stdio package with private credentials; Codex setup comes first.
codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latestUse 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: Creatomate MCP Server
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 |
What you can ask it | |
Quick install | |
Set up fal.ai access | |
Connect your client | |
Check it works | |
Output, flags and exit codes | |
MCP or CLI and token cost | |
Every tool and argument | |
Model and asset workflows | |
Exact reviewed batches and pagination | |
Several private accounts | |
Writing safely | |
How the two surfaces work | |
Your data | |
Environment variables | |
Updates and removal | |
Troubleshooting | |
API coverage and comparisons | |
Versions and migration | |
FAQ |
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.
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 loginNode 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.
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.
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.
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.
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.
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.
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@latestfal-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 --agentPublic 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.
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-pricingFlag | Behavior |
--agent | Compact JSON and no prompts; never confirms a write |
--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 |
1 | Unexpected error |
2 | Invalid input or refused policy operation, an unknown command or a hidden write |
3 | Not found |
4 | Provider authentication/permissions |
5 | Provider/network/unknown outcome |
7 | Rate limit |
10 | Missing or invalid local account credentials/configuration |
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.
Measured on 2026-10-05 against 2.0.2, the same day, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:
Cost | 2.0.2 | 3.0.0 |
Claude Code, every tool loaded, every message | 41,570 | 40,519 |
Claude Code's default, tool search, every message | 1,316 | 1,319 |
| 1,290 | 1,340 |
Codex over the CLI, one task, median of five | 127,484 | 105,371 |
Codex over MCP, the same task, median of five | 77,462 | 77,596 |
The task was "find the command that estimates what a generation will cost, and the flags it requires". Over the CLI, three 2.0.2 runs guessed an estimate command that does not exist, because 2.0.2's help listed none, and every extra step carries the whole conversation forward; every 3.0.0 run asked which. Over MCP, Codex prints its own TypeScript rendering of the tool list and keeps its first and last 20,000 characters or so: the whole rendering is 532 tokens shorter on 3.0.0, but the part Codex keeps holds about 57 more, which each later request carries. SKILL.md costs 50 more because it now says how approval works over MCP and lists every exit code.
Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.
search_modelsUnified 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| 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 |
| No; body/guard requirements still apply | string | Free-text search query to filter models by name, description, or category |
| No; body/guard requirements still apply | string | Filter by category (e.g., 'text-to-image', 'image-to-video', 'training') |
| No; body/guard requirements still apply | string | Filter models by status - omit to include all statuses enum: |
| 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) |
| 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_pricingReturns 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 |
| 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 |
| 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_pricingComputes 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 |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| 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. |
| 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: |
input.payload
input.payload oneOf branch 1
Argument | Required | Type | Details |
| Yes | string | Estimate type: historical API pricing based on past usage patterns enum: |
| Yes | object | Map of endpoint IDs to call quantities |
input.payload.oneOf1.endpoints
input.payload.oneOf1.endpoints.{key}
Argument | Required | Type | Details |
| Yes | integer | Number of API calls to estimate (regardless of units per call) minimum: |
input.payload oneOf branch 2
Argument | Required | Type | Details |
| Yes | string | Estimate type: unit price calculation based on billing units enum: |
| Yes | object | Map of endpoint IDs to unit quantities |
input.payload.oneOf2.endpoints
input.payload.oneOf2.endpoints.{key}
Argument | Required | Type | Details |
| Yes | number | Number of billing units expected (e.g., number of images, videos, etc.) minimum: |
get_usageReturns 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| 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. |
| 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. |
| 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: |
| 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: |
| 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: |
| 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 |
| 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 |
| 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 |
| 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: |
| 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_analyticsTime-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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| 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. |
| 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. |
| 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: |
| 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: |
| 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: |
| 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 |
| 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: |
| 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_eventsReturns 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| 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. |
| 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. |
| 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 |
| 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 |
| 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 |
| 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 |
| 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). |
| 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_payloadsDeletes 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 |
| Yes | string | Unique identifier for the request (UUID format) format: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
list_requests_by_endpointLists 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 |
| No; body/guard requirements still apply | integer | Number of items to return per page (max 100) minimum: |
| No; body/guard requirements still apply | string | Pagination cursor encoding the page number |
| 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 |
| 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. |
| 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. |
| No; body/guard requirements still apply | string | Filter by request status enum: |
| No; body/guard requirements still apply | string | Filter by specific request ID format: |
| No; body/guard requirements still apply | JSON | Fields to expand in the response. Use payloads to include input and output payloads. |
| No; body/guard requirements still apply | string | Sort results by end time or duration enum: |
| 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_requestsSearch, 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text search query for semantic search. Mutually exclusive with image_url and video_url. |
| No; body/guard requirements still apply | string | Image URL for similarity search. Mutually exclusive with query and video_url. |
| No; body/guard requirements still apply | string | Video URL for similarity search. Mutually exclusive with query and image_url. |
| 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). |
| No; body/guard requirements still apply | string | Deprecated: use |
| No; body/guard requirements still apply | boolean | Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests. |
| No; body/guard requirements still apply | boolean | Only include requests made via API keys. Mutually exclusive with exclude_api_requests. |
| 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: |
| 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_workflowsList 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Search by workflow name or title |
| 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. |
| 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_workflowCreate 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 |
| No; body/guard requirements still apply | string | Unique workflow name/slug within the user's namespace maxLength: |
| No; body/guard requirements still apply | string | Human-readable workflow title minLength: |
| No; body/guard requirements still apply | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| 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 |
| Yes | object | Input fields schema |
| 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 |
| Yes | string | Unique workflow name/slug within the user's namespace maxLength: |
| Yes | string | Human-readable workflow title minLength: |
| Yes | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
input.payload.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| 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 |
| Yes | object | Input fields schema |
| 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_workflowGet 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 |
| Yes | string | The username of the workflow owner maxLength: |
| Yes | string | The workflow name/slug maxLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
list_assetsBrowse 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text query for hybrid semantic search |
| No; body/guard requirements still apply | string | fal-hosted image URL to use for semantic image search format: |
| No; body/guard requirements still apply | string | fal-hosted video URL to use for semantic video search format: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more media types default: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more indexed sources default: |
| No; body/guard requirements still apply | string | Asset library section to browse enum: |
| No; body/guard requirements still apply | string | Collection scope to browse |
| No; body/guard requirements still apply | ['array', 'null'] | Character identifiers to use as @mention semantic filters default: |
| No; body/guard requirements still apply | ['array', 'null'] | Tag IDs to filter by default: |
| No; body/guard requirements still apply | string | Whether tag filters match any tag or all tags enum: |
| 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_collectionsList asset collections for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of collections to return minimum: |
| No; body/guard requirements still apply | ['integer', 'null'] | Number of collections to skip minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_collectionCreate asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| 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: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| 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: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
get_asset_collectionGet asset collection for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
update_asset_collectionUpdate asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
delete_asset_collectionDelete asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
get_asset_collection_hierarchyGet 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
favorite_asset_collectionFavorite 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
unfavorite_asset_collectionUnfavorite 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
move_asset_collectionMove 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| 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: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| 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: |
list_asset_collection_assetsBrowse assets in a collection for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text query for hybrid semantic search |
| No; body/guard requirements still apply | string | fal-hosted image URL to use for semantic image search format: |
| No; body/guard requirements still apply | string | fal-hosted video URL to use for semantic video search format: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more media types default: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more indexed sources default: |
| No; body/guard requirements still apply | string | Asset library section to browse enum: |
| No; body/guard requirements still apply | ['array', 'null'] | Character identifiers to use as @mention semantic filters default: |
| No; body/guard requirements still apply | ['array', 'null'] | Tag IDs to filter by default: |
| No; body/guard requirements still apply | string | Whether tag filters match any tag or all tags enum: |
| 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_collectionAdd 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
remove_asset_from_collectionRemove 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 |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_charactersList asset characters for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of collections to return minimum: |
| No; body/guard requirements still apply | ['integer', 'null'] | Number of collections to skip minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_characterCreate 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 |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.reference_images
input.reference_images[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| Yes | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| Yes | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
input.payload.reference_images
input.payload.reference_images[]
Native JSON value; inspect the full schema for validation.
update_asset_characterUpdate 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 |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.reference_images
input.reference_images[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
input.payload.reference_images
input.payload.reference_images[]
Native JSON value; inspect the full schema for validation.
get_asset_characterGet asset character for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
delete_asset_characterDelete asset character for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
favorite_asset_characterFavorite 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 |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
unfavorite_asset_characterUnfavorite 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 |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
list_asset_tagsList asset tags for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_tagCreate asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Tag name minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Tag name minLength: |
set_asset_tags_for_assetSet 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 |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | array | Full replacement set of tag IDs |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.tag_ids
input.tag_ids[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| 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_tagUpdate asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Tag name minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Tag name minLength: |
delete_asset_tagDelete asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
upload_assetUpload asset for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | fal-hosted media URL to ingest into the asset library format: |
| No; body/guard requirements still apply | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| No; body/guard requirements still apply | array | Tag IDs to assign to the uploaded asset default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.tag_ids
input.tag_ids[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| Yes | string | fal-hosted media URL to ingest into the asset library format: |
| Yes | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| 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_assetGet 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 |
| Yes | string | Vector ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
get_asset_lineageGet 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 |
| Yes | string | Asset ID minLength: |
| No; body/guard requirements still apply | integer | Maximum traversal depth (levels of derivation edges) minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
favorite_assetFavorite 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 |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unfavorite_assetUnfavorite an asset by request ID or vector ID.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_tags_for_assetList 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 |
| Yes | string | Vector ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
assign_asset_tagAssign 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 |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unassign_asset_tagUnassign 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 |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
get_storage_file_aclReturns 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 |
| 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: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
set_storage_file_aclReplaces 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 |
| 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: |
| No; body/guard requirements still apply | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.rules
input.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| 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 |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
sign_storage_file_urlCreates 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 |
| 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: |
| No; body/guard requirements still apply | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
| Yes | string | Required absolute new owner-private file; signed credential URL is never echoed. minLength: |
input.payload
Argument | Required | Type | Details |
| Yes | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
get_storage_settingsReturns 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 |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
update_storage_settingsReplaces 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 |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| No; body/guard requirements still apply | ['object', 'null'] | Default ACL applied to newly uploaded files. Null uses the system default (public). |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| 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. |
| 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: |
input.initial_acl
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| 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 |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| 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 |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| 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 |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
get_account_billingReturns 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 |
| No; body/guard requirements still apply | JSON | Data to include in the response. Use 'credits' to include current credit balance. |
| 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_teamsReturns 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 |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
get_organization_usageReturns 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 |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| 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. |
| 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. |
| 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: |
| 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: |
| 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: |
| 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 |
| 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 |
| 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. |
| 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). |
| 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: |
| 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_infoExact 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
run_modelConfirmed 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
submit_jobConfirmed 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
generate_imageConfirmed 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
generate_videoConfirmed 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
get_job_statusOne 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | boolean | Include native provider logs only when requested. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
get_job_resultOne 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
cancel_jobConfirmed 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 |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
upload_fileConfirmed 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 |
| Yes | string | Absolute selected local media file, regular/non-symlink, 1 byte–20 MiB. minLength: |
| Yes | string | Plain MIME type matching the selected media. pattern: |
| 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. |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
list_accountsLocal 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_schemaLocal 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 |
| Yes | string | Native field; use the reviewed provider reference. enum: |
preview_generation_batchRead-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 |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
input.tasks
input.tasks[]
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
input.tasks[].lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.tasks[].lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.tasks[].lifecycle.initial_acl.rules
input.tasks[].lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
submit_generation_batchConfirmed 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 |
| 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: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| Yes | string | Native field; use the reviewed provider reference. pattern: |
input.tasks
input.tasks[]
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| 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. |
| 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: |
input.tasks[].lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.tasks[].lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.tasks[].lifecycle.initial_acl.rules
input.tasks[].lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
search_models: GET /modelsUnified 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
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| 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 |
| False | {"type": "string", "description": "Free-text search query to filter models by name, description, or category"} |
query |
| False | {"type": "string", "description": "Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')"} |
query |
| False | {"type": "string", "enum": ["active", "deprecated"], "description": "Filter models by status - omit to include all statuses"} |
query |
| 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)"} |
get_pricing: GET /models/pricingReturns 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.
Location | Parameter | Required | Native shape |
query |
| 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"} |
estimate_pricing: POST /models/pricing/estimateComputes 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.
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 |
| Yes | string | Estimate type: historical API pricing based on past usage patterns enum: |
| Yes | object | Map of endpoint IDs to call quantities |
body.oneOf1.endpoints
body.oneOf1.endpoints.{key}
Argument | Required | Type | Details |
| Yes | integer | Number of API calls to estimate (regardless of units per call) minimum: |
body oneOf branch 2
Argument | Required | Type | Details |
| Yes | string | Estimate type: unit price calculation based on billing units enum: |
| Yes | object | Map of endpoint IDs to unit quantities |
body.oneOf2.endpoints
body.oneOf2.endpoints.{key}
Argument | Required | Type | Details |
| Yes | number | Number of billing units expected (e.g., number of images, videos, etc.) minimum: |
get_usage: GET /models/usageReturns 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.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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."} |
get_analytics: GET /models/analyticsTime-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.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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."} |
get_billing_events: GET /models/billing-eventsReturns 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.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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)."} |
delete_request_payloads: DELETE /models/requests/{request_id}/payloadsDeletes 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.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "format": "uuid", "description": "Unique identifier for the request (UUID format)"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
list_requests_by_endpoint: GET /models/requests/by-endpointLists 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
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Number of items to return per page (max 100)"} |
query |
| False | {"type": "string", "description": "Pagination cursor encoding the page number"} |
query |
| 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 |
| 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 |
| 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 |
| False | {"type": "string", "enum": ["success", "error", "user_error"], "description": "Filter by request status"} |
query |
| False | {"type": "string", "format": "uuid", "description": "Filter by specific request ID"} |
query |
| 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 |
| False | {"type": "string", "enum": ["ended_at", "duration"], "default": "ended_at", "description": "Sort results by end time or duration"} |
search_requests: GET /models/requests/searchSearch, 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
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text search query for semantic search. Mutually exclusive with image_url and video_url."} |
query |
| False | {"type": "string", "description": "Image URL for similarity search. Mutually exclusive with query and video_url."} |
query |
| False | {"type": "string", "description": "Video URL for similarity search. Mutually exclusive with query and image_url."} |
query |
| 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 |
| False | {"type": "string", "description": "Deprecated: use |
query |
| False | {"type": "boolean", "description": "Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests."} |
query |
| False | {"type": "boolean", "description": "Only include requests made via API keys. Mutually exclusive with exclude_api_requests."} |
query |
| 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."} |
list_workflows: GET /workflowsList 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
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Search by workflow name or title"} |
query |
| 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."} |
create_workflow: POST /workflowsCreate 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.
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 |
| Yes | string | Unique workflow name/slug within the user's namespace maxLength: |
| Yes | string | Human-readable workflow title minLength: |
| Yes | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
body.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| 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 |
| Yes | object | Input fields schema |
| 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.
get_workflow: GET /workflows/{username}/{workflow_name}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
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The username of the workflow owner"} |
path |
| True | {"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The workflow name/slug"} |
list_assets: GET /assetsBrowse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text query for hybrid semantic search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"} |
query |
| 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 |
| 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 |
| False | {"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"} |
query |
| False | {"type": "string", "description": "Collection scope to browse"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"} |
query |
| False | {"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"} |
list_asset_collections: GET /assets/collectionsList asset collections for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"} |
query |
| False | {"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"} |
create_asset_collection: POST /assets/collectionsCreate asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| 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: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
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 |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
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 |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
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 |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
get_asset_collection_hierarchy: GET /assets/collections/{collection_id}/hierarchyGet 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 |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
favorite_asset_collection: POST /assets/collections/{collection_id}/favoriteFavorite an asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
unfavorite_asset_collection: POST /assets/collections/{collection_id}/unfavoriteUnfavorite an asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
move_asset_collection: POST /assets/collections/{collection_id}/moveMove 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 |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| 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: |
list_asset_collection_assets: GET /assets/collections/{collection_id}/assetsBrowse assets in a collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text query for hybrid semantic search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"} |
query |
| 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 |
| 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 |
| False | {"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"} |
query |
| False | {"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"} |
add_asset_to_collection: POST /assets/collections/{collection_id}/assetsAdd 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.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
remove_asset_from_collection: DELETE /assets/collections/{collection_id}/assetsRemove an asset from a manual or character collection by request ID or vector ID.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_characters: GET /assets/charactersList asset characters for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"} |
query |
| False | {"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"} |
create_asset_character: POST /assets/charactersCreate 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.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| Yes | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
body.reference_images
body.reference_images[]
Native JSON value; inspect the full schema for validation.
update_asset_character: PATCH /assets/characters/{character_id}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.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| 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: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
body.reference_images
body.reference_images[]
Native JSON value; inspect the full schema for validation.
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 |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
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 |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
favorite_asset_character: POST /assets/characters/{character_id}/favoriteFavorite an asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
unfavorite_asset_character: POST /assets/characters/{character_id}/unfavoriteUnfavorite an asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
list_asset_tags: GET /assets/tagsList 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 |
create_asset_tag: POST /assets/tagsCreate asset tag for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Tag name minLength: |
set_asset_tags_for_asset: PUT /assets/tagsSet 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 |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| Yes | array | Full replacement set of tag IDs |
body.tag_ids
body.tag_ids[]
Native JSON value; inspect the full schema for validation.
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 |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Tag name minLength: |
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 |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
upload_asset: POST /assets/uploadsUpload asset for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | fal-hosted media URL to ingest into the asset library format: |
| Yes | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| 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.
get_asset: GET /assets/{vector_id}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.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Vector ID"} |
get_asset_lineage: GET /assets/{asset_id}/lineageGet 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.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Asset ID"} |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 5, "default": 5, "description": "Maximum traversal depth (levels of derivation edges)"} |
favorite_asset: POST /assets/favoriteFavorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unfavorite_asset: POST /assets/unfavoriteUnfavorite an asset by request ID or vector ID.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_tags_for_asset: GET /assets/{vector_id}/tagsList 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 |
| True | {"type": "string", "minLength": 1, "description": "Vector ID"} |
assign_asset_tag: POST /assets/tags/{tag_id}/assignAssign 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 |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unassign_asset_tag: DELETE /assets/tags/{tag_id}/assignUnassign a tag from an asset by request ID or vector ID.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
get_storage_file_acl: GET /storage/files/aclReturns 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.
Location | Parameter | Required | Native shape |
query |
| 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."} |
set_storage_file_acl: PUT /storage/files/aclReplaces 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.
Location | Parameter | Required | Native shape |
query |
| 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 |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
body.rules
body.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
sign_storage_file_url: POST /storage/files/signCreates 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.
Location | Parameter | Required | Native shape |
query |
| 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 |
| Yes | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
get_storage_settings: GET /storage/settingsReturns 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.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
update_storage_settings: PUT /storage/settingsReplaces 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.
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 |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| 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 |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| 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 |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
get_account_billing: GET /account/billingReturns 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
Location | Parameter | Required | Native shape |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Data to include in the response. Use 'credits' to include current credit balance."} |
get_organization_teams: GET /organization/teamsReturns 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.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
get_organization_usage: GET /organization/usageReturns 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.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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."} |
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.
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.
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.
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-settingspreview_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 --agentUse 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 --helpAll 34 mutations, paid runs, cancellation, local input uploads and private signed-output files require --confirm or confirm:true through the same write 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.
Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm:true counts. FAL_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask.
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, who approved each call, operation names and static summaries, then whether the call was done or failed, 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.
One ALL_TOOLS catalogue provides actual JSON schemas and handlers. Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition, so both derive the same flags and call the same handler and write 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.
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.
Setting | Effect |
| Private account API key; ignored as a fallback when named profiles are explicitly configured. |
| Absolute owner-private regular token-only file; overrides selected direct key. |
| Private unique {name,api_key,token_file} account profiles. |
| Exact selected profile label; provider owner is not inferred. |
| 1/true hides and directly refuses every non-read task. |
| 0/false refuses confirmed paid/mutating/file-write tasks. |
| Optional best-effort append-only guard decision file, no payload/key. |
| Default 30000; 100–300000 permitted; no auto retry. |
| Default 350; 0–10000 permitted; process-wide request spacing, not a provider/cross-process limiter. |
|
|
|
|
| Give up on any tool after this long |
| For |
| Comma-separated browser origins allowed to call |
|
|
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-cliSymptom | 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. |
Offering | Reviewed surface | Useful capabilities and limits |
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. | |
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. | |
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. | |
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. | |
@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.
Component | Reviewed version |
Package/desktop manifest | 3.0.1 |
Node runtime | >=22 |
Slipway | 0.1.17 |
MCP TypeScript SDK, through Slipway | 2.3.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.
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.
Yes, for this package. In Claude Code the CLI costs nothing until it is used, plus about 1,340 tokens for SKILL.md once, where the server costs about 1,320 tokens a message with tool search and 40,500 with every tool loaded. In Codex, finding the pricing command and its flags took a median of 105,371 input tokens over the CLI and 77,596 over MCP. Section 7 has how each was measured.
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.
Open a sanitized issue. Use SECURITY.md for private reports.
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. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.
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.
Runtime: Slipway, which brings the MCP TypeScript SDK, plus Ajv and ajv-formats. Development: TypeScript, Vitest, Vite and MCPB. Exact locked versions appear above. Packaging tools are excluded from desktop runtime.
Preserves AGPL-3.0 and existing private legacy history. Read THIRD_PARTY_NOTICES.md. fal.ai service terms and trademarks remain separate.
© 2026 Navid Media. Made with ❤️ by Navid Moazzez.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description adds genuinely non-obvious behavior: unresolved request/vector references are materialized into assets before local collection state is mutated, and character collections are mutated indirectly via tag application. It still does not mention the confirm gate or the retry/idempotency story.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and then the two non-obvious behaviors (materialization, character-tag path). 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter destructive write with a nested payload object, three body-input modes, and no output schema, the description omits the confirm contract ('set true only when the user asked for exactly this action') and the idempotency key, both of which materially affect correct invocation. It covers the asset-reference semantics well but leaves the safety-relevant inputs to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, but the description adds real meaning: request_id and vector_id are alternative ways to name the asset and are materialized first. It does not explain the payload/payload_file/flat-body mutual exclusivity or the confirm parameter, which remain schema-only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (add an asset to a collection) and distinguishes the two collection types it applies to (manual vs character). The inverse sibling remove_asset_from_collection is never named, but the operation is unambiguous and the character-collection nuance goes beyond a bare restatement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (adding an asset to a manual or character collection) and gives a conditional rule for character collections, but never states when NOT to use it, nor points to alternatives such as remove_asset_from_collection or create_asset_character. Usage is inferable 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 a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Tag ID | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 structurally. The description adds genuine behavioral context beyond them: unresolved request/vector references are materialized (a persisted asset is created) before the tag state is added, warning the agent of an extra side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core action front-loaded before the reference-handling caveat. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, nested payload objects and no output schema, the description is thin: it omits the confirm guard semantics and retry behavior tied to Idempotency_Key, relying on the schema to carry that load. It is adequate but leaves meaningful gaps for a high-risk write.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 confirm, Idempotency_Key, payload and payload_file. The description echoes only the vector_id/request_id path and 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Assign a tag to an asset"), which is clear and distinct from the obvious inverse sibling unassign_asset_tag. However, it never differentiates itself from set_asset_tags_for_asset or create_asset_tag, so sibling routing remains partly inferential.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no alternative tool is named despite several overlapping tag siblings (set_asset_tags_for_asset, create_asset_tag, unassign_asset_tag). The second sentence addresses how to supply inputs, not when to select this tool over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact configured isolated API-key profile label. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them: a cancellation receipt is not proof that processing stopped or credits were refunded, eligibility is governed by current provider state, and retrying is discouraged. That is substantive behavioral context, though it omits permission/auth prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler; the core action is stated first and the caveats follow. Sentence-fragment style is terse and readable, though the clipped phrasing slightly hurts clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 description covers the critical caveats (receipt is not proof, provider state controls eligibility, no retry) and 100% of parameters are schema-documented. What is missing is the expected return shape beyond the receipt and any auth/permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents account, confirm, model_id and request_id in detail. The description only weakly gestures at the confirm parameter with the word 'Confirmed' and adds no syntax or format meaning 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (cancellation of a queued request/job) and the tool name plus title make the resource clear. It does not, however, distinguish itself from nearby siblings like delete_request_payloads or get_job_status, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use / when-not-to-use guidance and no named alternative among the many job-related siblings. The only directive offered is the terse 'No retry,' which is a constraint rather than a usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Character display name | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower. The description still adds real behavioral context beyond them: unresolved ID references are 'materialized before character state is added,' and creation is scoped to the authenticated user. It does not explain the confirm gate or the union-body/payload_file handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then input-referencing rules, then materialization behavior. No filler, though the middle sentence is repeated almost verbatim in the schema $defs, slightly diluting value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and with 90% schema coverage the description plus schema cover most of what an agent needs. Gaps remain around the payload vs flat-flags vs payload_file mutual exclusion and the confirm flag, but those are documented in the schema itself rather than the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 90%, so the structured fields already document nearly every parameter, and the description's reference_images preference sentence largely duplicates the $defs description. Baseline 3 is appropriate: it adds little beyond what the schema already says for the 10 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create an asset character') plus its scope ('for the authenticated user's fal Assets library'). The verb immediately disambiguates it from the sibling list/get/update/delete_asset_character tools without the agent needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers input-level guidance ('Prefer vector IDs or request IDs in reference_images... use fal-hosted image URLs only for standalone images'), but never addresses tool selection: no when-to-use, when-not-to-use, or pointer to update_asset_character for modifications. Usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create asset collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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. |
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 covered. The description adds no behavioral context beyond scope: it never mentions the confirm gate ('Set true only when the user asked for exactly this action'), the idempotency key, or that the union body inputs are mutually exclusive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. It is tight, though the brevity here reflects under-specification rather than disciplined concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter, nested-object mutation with three mutually exclusive body forms, a confirm gate and no output schema, one scope sentence is not enough. The critical call-shaping details live only in schema text an agent may skim past.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 field, including payload vs flat flags vs payload_file exclusivity and the confirm flag. The description adds only ownership scope, not 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.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ('Create asset collection') plus scope ('authenticated user's fal Assets library'), which separates it from create_workflow, create_asset_character and create_asset_tag. It never names a sibling or draws the boundary against update_asset_collection, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, no alternatives. With siblings like list_asset_collections, update_asset_collection and delete_asset_collection present, the agent gets nothing about when creating a collection is the right call versus nesting into an existing one (parent_collection_id).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create asset tag for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Tag name | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 covered. The description adds nothing beyond that — it does not explain what 'destructive' means for a tag creation, whether duplicates are rejected or overwritten, or how the optional Idempotency_Key relates to the non-idempotent annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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 extreme terseness is part of why other dimensions are thin rather than a structure problem in itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (including a nested payload union), zero required fields, no output schema, and a destructive/non-idempotent annotation profile, the description is far too thin. It never clarifies that a tag is created but not attached to any asset, nor addresses the confirm and Idempotency_Key semantics that an agent needs to call this safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 name, account, confirm, payload, payload_file, and Idempotency_Key in detail. The description adds no parameter meaning beyond the schema, 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.
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 asset tag') and scopes it to the authenticated user's fal Assets library, which cleanly separates it from read-oriented siblings like list_asset_tags. It does not name or contrast with update_asset_tag/delete_asset_tag, but the verb alone makes the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to create a tag versus reusing an existing one, no mention of prerequisites (e.g., whether the tag must later be assigned via assign_asset_tag to be useful), and no exclusion criteria. The only signal is the generic reference to the user's Assets library.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| contents | No | ||
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds useful context the annotations don't carry: authentication is required, the resource is namespaced, and duplicate names yield a 400 validation error. It does not, however, explain the destructive hint or the mutually-exclusive body options (payload vs flat flags vs payload_file), so it only partially deepens the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then auth and use cases, with a useful uniqueness constraint at the end. The bolded section headers are efficient; only the 'Common Use Cases' list is mildly expendable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter nested create tool with no output schema, the description covers purpose, auth, ownership, use cases, and the key duplicate-name failure mode. The remaining complexity (body union, is_public, confirm semantics) is adequately handled by the schema, leaving no critical gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 88%, so the schema already documents nearly all 8 parameters, including the mutually-exclusive payload/contents/payload_file body shapes. The description adds no parameter-level syntax or semantics 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.
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 clarifies ownership ('owned by the authenticated user'). An agent can readily tell it apart from the list_workflows/get_workflow siblings, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' section gives clear when-to-use context (save a newly built workflow, programmatically provision workflows). It stops short of naming alternatives or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete asset character for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| character_id | Yes | Character collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered without the description. The description adds only the ownership scope ('authenticated user's fal Assets library') and says nothing about whether deletion is permanent, whether the confirm flag is enforced, or what happens to assets referencing the character.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler or redundancy. It is efficient, though the brevity leans toward under-specification rather than tight information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 consequences an agent needs: permanence, what the response returns, whether the caller must pass confirm=true in practice, and any permission requirements. The schema documents the inputs, but the description leaves the agent under-informed about the act itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with character_id, account, confirm, and Idempotency_Key all documented inline, so the baseline is 3. The description adds no parameter-level meaning of its own (e.g., it never explains the confirm gate or the account label), so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Delete asset character') and scopes it to the authenticated user's fal Assets library, which distinguishes it from the other delete_* siblings (delete_asset_collection, delete_asset_tag, delete_request_payloads). It stops short of explicitly contrasting when this resource applies versus those siblings, but the resource noun is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 update_asset_character or unfavorite_asset_character. The reader gets no signal about the conditions under which deleting a character is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete asset collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| collection_id | Yes | Collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
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. The description adds nothing beyond that: it never says what happens to the assets inside the collection, whether the collection must be empty, or that the deletion cannot be undone. For a destructive collection delete, the cascade behavior is the key unknown and it is unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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 efficiency comes at the cost of substance rather than from tight editing of rich content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent delete with no output schema, the description should at minimum describe irreversibility and the fate of contained assets. Annotations cover safety hints and the schema covers parameters, but the behavioral consequences of the call remain unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 mentions no parameters at all; it neither explains the confirm flag semantics nor the account/idempotency fields, leaving the schema to carry all parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Delete asset collection') plus a scope ('authenticated user's fal Assets library'), which separates it from write siblings like create_asset_collection and update_asset_collection. It does not, however, distinguish itself from the other delete_* tools (delete_asset_tag, delete_asset_character) beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 alternatives are named. There is no hint that the action is irreversible, that a confirm flag should be set, or how to obtain the collection_id — an agent gets no routing or precondition information from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete asset tag for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Tag ID | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
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, covering the safety profile fully. The description adds nothing beyond that — it doesn't explain the confirm guard, the effect on assets currently holding the tag, or why an Idempotency_Key exists alongside 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. It is efficient, though the terseness edges toward under-specification rather than disciplined brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation the annotations carry the safety burden and there is no output schema to explain. Still, the description omits the confirm requirement and the delete-vs-unassign distinction, leaving gaps an agent must infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the schema, setting the baseline at 3. The description adds no additional meaning about tag_id, account, confirm, or Idempotency_Key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 tag) scoped to the authenticated user's fal Assets library, so the core action is unambiguous. It does not, however, distinguish itself from close siblings like update_asset_tag, assign_asset_tag, or unassign_asset_tag, which an agent could easily confuse with deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. The most important routing ambiguity — deleting a tag entirely versus unassigning it from an asset — is left unaddressed despite unassign_asset_tag being a direct sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| request_id | Yes | Unique identifier for the request (UUID format) | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive, open-world, and non-idempotent by default, but the description adds substantial specificity: exactly what is deleted (payload data and CDN output files), what is not deleted (input CDN files shared by other requests), irreversibility, admin-key authentication requirement, and idempotency-key retry behavior with a 10-minute response cache. This is rich, useful context 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in one sentence, followed by bold headings and bullet lists that cleanly separate important constraints, deletion scope, response details, and idempotency. The length is justified by the destructive admin operation, and every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the response shape (deletion status per CDN file and any errors). Annotations cover destructiveness and open-world behavior, while the description fills in authentication, irreversibility, exact deletion boundaries, and retry semantics, leaving no material gap for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented. The description adds value for the Idempotency-Key parameter (prevents duplicate deletions, 10-minute cache) but does not clarify account or confirm, so it only partially extends parameter semantics. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a specific verb, resource, and scope: 'Deletes the IO payloads and associated CDN output files for a specific request.' It is clearly distinguishable from sibling delete tools such as delete_asset_collection, delete_asset_character, and delete_asset_tag because it targets request payloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (admin API key required, irreversible, only output CDN files deleted) but does not explicitly say when to use this tool versus alternative delete_* siblings. It implies the usage but lacks direct routing or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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 adds genuine context beyond them: authentication is required, and custom pricing or 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first line, and the header/bullet structure maps cleanly onto the union schema. Some bullets are redundant with the schema descriptions, but the size is defensible for a tool with two mutually exclusive call shapes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Auth requirements, method selection, and use cases are all covered, which is what an agent needs to invoke it. With no output schema, the description should ideally say what an estimate returns (cost, currency, per-endpoint breakdown), and that return-shape gap is the main omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 two-method framing and the worked examples ('100 calls to flux/dev', '50 images from flux/dev') clarify how call_quantity and unit_quantity differ, but the text largely restates the union schema's own descriptions and says nothing about the `account` parameter or the payload/payload_file exclusivity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('computes cost estimates') and breaks the operation into two concrete methods with examples. It does not, however, differentiate itself from closely related siblings such as get_pricing, get_billing_events, or get_analytics, so an agent must infer which pricing tool to reach for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use guidance for each of the two methods (historical usage patterns vs known output quantity) plus common use cases and the authentication prerequisite. It stops short of any exclusion or routing advice relative to sibling pricing/usage tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 context beyond the schema by explaining that unresolved references are materialized before favorite state is added, but it never explains why this read-like action is flagged destructive or how idempotency behaves on retry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by the key input expectation. There is little waste, though the materialization clause is slightly dense for a single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with a nested payload object and no output schema, the description is adequate but thin: it omits any mention of the confirm flag, the payload_file/payload mutual exclusion, and the idempotency key, relying entirely on the schema to carry those. The core 'favorite an asset' intent is covered, but the mutation-safety context an agent needs is not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, payload, vector_id, request_id, payload_file and Idempotency_Key. The description only echoes the request_id/vector_id choice and adds no format, mutual-exclusion, or size constraints beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Favorite') and resource ('an asset'), which distinguishes it from the many sibling mutation tools. It does not explicitly name alternatives like favorite_asset_character or unfavorite_asset, but the resource noun is clear enough to separate it from the collection/character variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an implicit usage cue ('Provide a request ID or vector ID'), implying it is used when you have one of those identifiers. It offers no when-not guidance, no mention of the confirm flag or prerequisites, and no routing to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Favorite an asset character for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| character_id | Yes | Character collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds only the scope of the user's fal Assets library, without elaborating on reversibility, effects, or the idempotency key behavior. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It is concise and easy to parse, though very sparse for a tool operating in a dense sibling environment.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations cover the safety profile and the schema covers all parameters, so the core mechanics are clear. However, the lack of sibling differentiation and when-to-use guidance leaves a routing gap for an agent with many similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Favorite an asset character') and scopes it to the authenticated user's fal Assets library. It does not distinguish this tool from siblings like favorite_asset or favorite_asset_collection, so it lacks the differentiation needed for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus the many sibling favorites tools (favorite_asset, favorite_asset_collection, unfavorite_asset_character). It also does not mention the 'confirm' parameter's condition, which is only explained in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Favorite an asset collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| collection_id | Yes | Collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
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 description's only addition is the 'authenticated user's library' scope. It says nothing about what happens on repeat calls (idempotentHint=false) or that the operation is effectively irreversible, which matters for a tool flagged destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no waste; the verb and target come first. It is efficient, though its brevity is partly under-specification rather than economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering the safety profile and 100% schema coverage, the description does not need to restate parameters or return values (no output schema exists). It is minimally adequate, but among 60+ siblings a mutation tool should at least route the agent away from unfavorite_asset_collection and note the confirm requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 unusual 'account' label semantics and the confirm gate) are already documented in the schema. 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.
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'), and scopes it to the authenticated user's fal Assets library. However, it never mentions the near-identical sibling unfavorite_asset_collection, so the agent gets no explicit disambiguation from the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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_collection, or when-not to use it. It also fails to mention the confirm gate that the schema implies is required for this action, leaving the invocation condition to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so safety is partly covered. The description adds genuinely new context: queue submissions return a receipt only, a synchronous timeout can leave an unknown paid outcome, and there is no retry or polling. This paid-outcome and no-retry disclosure is valuable 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and kept to a few dense sentences with no filler. The opening clause 'after current native input-schema validation' is somewhat opaque, but overall it is tight and earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and nested parameters, the description covers the key unknowns: paid cost, receipt-only returns for queued work, unknown outcome on synchronous timeout, and no retry/polling. Remaining gaps (auth/profile requirements, what a receipt contains) are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 including model_id, input, confirm, and lifecycle. The description reinforces the exactness requirement for model_id/input but adds no syntax, format, or defaulting detail beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The name and title establish image generation, and the description frames it as a 'confirmed paid model request' requiring exact model_id/input. However, the phrasing is jargon-heavy and it lumps 'image/video commands' together, giving no explicit differentiation from close siblings like generate_video, run_model, or submit_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the tool should only be invoked after confirmation ('Confirmed paid model request'), which is a real precondition. It does not, however, name alternatives or say when to prefer this over submit_job, run_model, or submit_generation_batch, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This is the strongest dimension: it discloses that the request is paid, that queue submissions return only a receipt, that a synchronous timeout can leave an unknown paid outcome, and that retry/polling is not supported. That is behavioral context well beyond the destructiveHint=false/true and idempotentHint=false annotations, and it directly warns about money-losing failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short, front-loaded clauses with no filler, and the riskiest fact (unknown paid outcome on timeout) is placed late but prominently. The register is telegraphic and jargon-heavy, which costs some readability but not much space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the return contract (receipt-only for queued submissions) and the failure semantics. Nested lifecycle/ACL parameters are documented in the schema, so nothing essential is missing, though the absence of explicit sibling routing leaves a small gap for a 6-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, but the description adds genuine meaning: model_id and input must be exact values from the current catalog, and callers must not invent fields or select defaults. That reinforces and sharpens the schema's own warnings rather than merely repeating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys a specific verb+resource: submitting a paid model request that is only issued after native input-schema validation, with exact model_id/input required. It never actually says 'video' (that lives in the name/title), so the action is clear but the resource type is inferred. It does not name the sibling tools (run_model, generate_image, submit_job) it must be distinguished from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives real constraints — do not invent fields or pick defaults, no retry or polling — which implicitly routes the agent away from re-submitting on timeout. However, it never explicitly says when to choose this over run_model, generate_image, or submit_job, leaving the alternative-selection decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| 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. |
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.
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.
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.
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.
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.
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.
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.
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds meaningful behavior: preparation vs execution duration semantics, the requirement that metrics be explicitly requested via expand, and defaults/cursor pagination context, none of which the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded with the core semantics and a clear metric catalog, but the 'Key Features' and 'Common Use Cases' blocks largely restate material already covered above (selective metrics, latency percentiles, error breakdown), inflating length without adding decisions the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 carries return-value burden, and it adequately describes the metric shape and bucketing options. It is close to complete for a 10-parameter analytics tool, with only mild gaps around pagination behavior and the account parameter's meaning beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 earns more by enumerating the full set of valid expand metric values grouped by category (volume, error type, latency, cold boot, billing) and clarifying the prepare/duration distinction, which the schema's coarser expand description does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource with scope: 'Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles.' It clearly differentiates from nearby siblings like get_usage and get_billing_events by being per-endpoint performance/latency analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a usage context ('Use with the Queue/Webhooks flow to monitor SLAs') and lists common use cases, and the expand section implies when metric selection matters. However it never names an alternative tool (e.g. get_usage or get_billing_events) or states when NOT to use this tool, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| vector_id | Yes | Vector ID |
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.
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.
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.
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.
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.
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 character for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| character_id | Yes | Character collection ID |
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.
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.
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.
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.
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.
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 collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| collection_id | Yes | Collection ID |
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.
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.
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.
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.
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.
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 the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| collection_id | Yes | Collection ID |
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.
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.
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.
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.
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.
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 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 |
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.
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.
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.
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.
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.
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.
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.
| 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 '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 |
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 only needs to add constraints beyond that. It does: a 10,000-record per-page cap and a 90-day date-range cap are operational limits not expressible in annotations, and the record field breakdown compensates for the absent output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The most important content (what it returns, with what filters) is front-loaded, and the feature/use-case bullets are scannable. There is mild redundancy, since 'Flexible date range filtering' and 'Optional endpoint filtering' repeat the opening sentence and several use cases restate features, but nothing is padded egregiously.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, ten-parameter list endpoint with no output schema, the description supplies the missing pieces: the per-record return fields and USD cost breakdown, pagination mechanics, page-size and date-range caps, and default time windows. An agent has everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 in detail, including date formats, array/comma syntax, and defaults. The description only restates 'endpoint' and 'date range' filtering generically, adding no syntax or format 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb and resource ('Returns paginated individual billing event records') and adds filters and scope. The emphasis on 'individual billing event records for each API request' distinguishes it by granularity from aggregate siblings like get_usage, get_analytics, and get_account_billing, so an agent can select it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' block gives concrete selection contexts: auditing individual events, tracking request volumes, debugging specific requests by ID, and monitoring per-request unit consumption. It lacks any explicit when-not or named alternative (e.g., 'for aggregate totals use get_usage'), which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. | |
| request_id | Yes | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. |
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.
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.
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.
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.
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.
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.
One read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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.
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.
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.
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.
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.
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.
Exact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.
| 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. |
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.
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.
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.
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.
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.
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.
Local current native method/path/query/header/body schema and exact provenance. No credential or provider request.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes |
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.
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds non-obvious context the annotations cannot: the admin-key requirement, the root-team scoping, and the enterprise availability gate, which materially affect whether a call can succeed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the return value, then availability, then auth requirement, and closes with feature bullets. Efficient and skimmable; the 'Key Features' bullets partially restate the opening sentence rather than adding new information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description compensates by enumerating returned fields (is_org_root, usernames, display names). Auth requirements and availability are both covered, so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional 'account' parameter, so the schema carries the semantics and baseline 3 applies. The description adds no syntax or meaning for the account parameter beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 disambiguates from siblings like get_organization_usage and list_accounts by naming teams as the subject. An agent can select it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear prerequisites: enterprise customers with organizations enabled, and must be called with an admin API key on the organization's root team. It stops short of naming an alternative tool or explicit when-not-to-use conditions, but the access gating is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical context beyond annotations: it requires an admin API key on the root team, is for enterprise organizations, and describes attribution via 'username' and 'product' fields. It also explains pagination, but not return format details. Annotations already cover read-only/idempotent safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then breaks down product lines and constraints with bullet-style key features. The >Availability blockquote is clear. It is well-structured but slightly verbose with the example and documentation link.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter read-only tool with no output schema, the description covers access requirements, product lines, and attribution fields. It misses describing the structure of returned records beyond the two fields mentioned, but annotations and schema fill some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 13 parameters thoroughly. The description lists some filterable fields (team_username, product, endpoint, api_key_id, date range, auth method) but doesn't add meaning beyond the schema. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Returns paginated usage records across all teams and product lines in your organization'), clearly distinguishing it from get_usage (which is presumably single-team/account) and get_organization_teams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States clear availability constraints ('enterprise customers with organizations enabled', 'admin API key on the organization's root team') and implied usage context. It doesn't explicitly differentiate from the sibling get_usage, though.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds genuine context on top: authentication is required and custom pricing/discounts may apply based on account status. It also discloses that pricing varies by billing model (output-based vs GPU-based), which is useful behavioral information not in 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core return meaning, then auth, then use cases, with an external link at the end. Well organized and mostly tight, though the use-case bullets and marketing-style bolding add some length without proportional value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 usefully explains that values are expressed per the model's billing unit in a given currency. Auth requirements and pricing-model variability are covered; only the account parameter's role and the response shape remain unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so endpoint_id and account are already fully documented in the schema (including the 1-50 ID limit and comma-separated vs array syntax). The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 that output is per billing unit in a currency. The purpose is unambiguous, but it never distinguishes itself from the close sibling estimate_pricing, leaving the agent to infer which one to call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' list (display pricing, compare models, build cost tools, check rates) implies when the tool is useful but is framed as use cases rather than when-to-use/when-not conditions. It never states the key routing rule against estimate_pricing, which is the most likely alternative for cost-related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
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 adds genuine value on top: it states the assets:read auth requirement and explains that rule users are returned as nicknames. It does not discuss pagination or rate limits, keeping it at a solid 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return statement, then a compact explanation of ACL composition, then the auth requirement. Well organized with no filler, though the ACL-structure sentence is slightly more than the minimum needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 describes the returned ACL shape (default decision plus per-user overrides) and the auth prerequisite. Complete enough for the agent to call and interpret the result, though it omits any handling of empty or missing ACLs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself documents both url and account in detail (including format and query-parameter constraint). The description adds no parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Returns') and a precise resource ('the Access Control List currently applied to a fal CDN file'), which an agent can easily tell apart from set_storage_file_acl. It does not explicitly name the write sibling, so it falls just short of the distinguishing-without-schema bar, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer this is the read path for inspecting ACLs before a set_storage_file_acl call, and the auth prerequisite ('API key must have assets:read') is given. There is no explicit when-to-use, when-not, or named alternative, so guidance is minimal-but-adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. |
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 goes beyond them by stating the required authentication scope (`account:settings:read`) and by explaining null-field semantics, including that both fields are null when settings were never saved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return summary, then a tight bullet list documenting each field, then an auth note. Every sentence carries information; only minor redundancy between the intro and bullets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly carries the burden of describing return values, documenting both fields and their null meanings, and disclosing the permission requirement. An agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One parameter with 100% schema description coverage, so the schema already documents the `account` key. The description adds only the vague qualifier 'account-level' and does not explain the parameter's semantics or the null/omitted behavior, so it adds little beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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. The scope word 'account-level' plus 'storage lifecycle' cleanly separates it from siblings like update_storage_settings, get_storage_file_acl, and get_usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by defining what the tool returns, and its read-only nature implicitly contrasts with update_storage_settings, but it never says when to call this versus alternatives such as get_storage_file_acl. No explicit routing or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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 |
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 genuinely useful behavior: what each line item contains (unit quantity, price, discount, cost_total formula), that results are paginated, and that defaults apply to the date range. It does not mention rate limits or cursor expiry, but the added detail is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is well front-loaded, but the 'Key Features' and 'Common Use Cases' bullets largely restate the same filter and pagination facts, and the external docs link adds little for an agent. It is not egregious, but several lines do not earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter read tool with no output schema, the description does a good job describing the shape of returned records and the pagination model, which compensates for the missing output schema. It is slightly thin on how expansion interacts with returned fields, but overall sufficient to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 defaults and enum semantics. The description only gestures at filters (endpoint, user, date range, auth method) without adding syntax or constraints 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb (returns) and resource (paginated usage records) scoped to 'your workspace', which usefully distinguishes it from organization-wide siblings like get_organization_usage. However, it does not differentiate itself from adjacent tools such as get_analytics, get_billing_events, or list_requests_by_endpoint, which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' block implies when the tool is useful (reports, dashboards, tracking), but it never states when NOT to use it or names an alternative sibling. An agent must infer the boundary against get_organization_usage and get_analytics on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| 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 |
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 one genuinely useful behavioral fact — authentication is required — plus the fact that the full definition is returned, but says nothing about permissions scope, error behavior on missing workflows, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose in the first sentence, then uses short labeled sections for auth and use cases. Formatting is slightly heavier than necessary for such a simple tool, but every line is relevant and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly notes that full contents/definition are returned and flags the auth requirement. For a simple three-parameter read tool this is nearly complete, with only minor gaps around failure modes or permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters documented, including the subtle 'account' label distinction, so the schema carries the burden. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get detailed information about a specific workflow') and clarifies the payload includes full contents/definition, which distinguishes it from a bare metadata fetch. It does not explicitly name the sibling it contrasts with (list_workflows), so it falls 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' list implies when to reach for this tool (editing, viewing config, exporting), which is helpful context. However, it offers no exclusions or alternatives — an agent is not told to use list_workflows to enumerate or create_workflow to make one, so guidance 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.
Local labels/default/auth method only. No keys, token paths, real provider identities or network request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
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.
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.
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.
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.
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 characters for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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.
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.
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.
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.
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.
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.
Browse assets in a collection for the authenticated user's fal Assets library.
| 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 |
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.
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.
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.
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.
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.
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 collections for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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.
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.
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.
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.
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.
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.
Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
| 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 |
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.
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.
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.
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.
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.
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 tags for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. |
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.
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.
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.
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.
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.
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 tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| vector_id | Yes | Vector ID |
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.
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.
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.
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.
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.
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.
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
| 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 |
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.
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.
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.
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.
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.
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 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
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: authentication is required and results are restricted to the caller's owned workflows, plus cursor-based pagination behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose in the first sentence, then uses bolded headers and bullets that are easy to scan. Slightly header-heavy for a simple list tool but every block carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 no output schema, the description covers auth scope, pagination, and filtering use cases, which is enough for correct invocation. It could say more about result shape now that no output schema exists, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 reiterates search and endpoint filtering but adds no syntax, format, or default details beyond what the schema already states, and it does nothing to clarify the ambiguous 'account' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List workflows for the authenticated user') with scoping ('optional search and filtering'), which clearly separates it from create_workflow and get_workflow. It stops short of explicitly naming those siblings, so it needs the reader 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Common Use Cases' section gives concrete contexts (display workflow library, search specific workflows, find workflows using particular models) that map directly to the search and used_endpoint_ids parameters. There is no explicit when-not or alternative-tool guidance, but the intended usage context is clearly conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 new behavioral constraints — that non-manual collections cannot be moved or act as folders, and that the 5-level depth and cycle rules are enforced — which the agent could not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The core action and destination are front-loaded, and the constraint sentence immediately follows with no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the mutation semantics and validity rules are covered by the description plus the 86%-covered schema (confirm, idempotency key, payload union). Missing only explicit failure/reversibility behavior, which is a minor gap for a move operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the schema already documents collection_id, parent_collection_id (including null = top level), confirm, payload, payload_file, and idempotency key. The description's nesting/cycle detail duplicates the parent_collection_id $defs text rather than extending it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Move a manual asset collection') plus the destination scope ('under another collection, or to the top level'). This is distinguishable from siblings like update_asset_collection or add_asset_to_collection without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives real eligibility constraints for when the move is valid (manual collections only, 5-level nesting cap, no cycles), which is more than most definitions offer. It stops short of naming the alternative sibling (e.g., update_asset_collection) for non-hierarchy edits, so it is clear context rather than full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
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.
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.
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.
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.
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.
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 an asset from a manual or character collection by request ID or vector ID.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 a real constraint by limiting applicability to manual/character collections, but says nothing about irreversibility, the confirm requirement, or whether the underlying asset survives removal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb, resource, scope and identifier options; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, eight-parameter tool with a nested payload union and no output schema, the description is minimal but the schema carries the invocation detail. It omits any top-level warning about payload/payload_file exclusivity or the confirm gate, leaving the agent to discover those only by reading the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all eight parameters, including the payload union and idempotency key, are documented in structured data. The description only echoes that request_id or vector_id may be used; the baseline 3 is appropriate 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.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (remove) and resource (asset from collection), and scopes it to 'manual or character' collections while naming the two accepted identifier kinds. It is clearly distinguishable from the sibling add_asset_to_collection, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, no mention of prerequisites, and no routing to alternatives. The critical confirm gate and the collection-type restriction are buried in the schema rather than surfaced as usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety bar is lower, yet the description adds real traits: the call incurs payment, a synchronous timeout can leave an unknown paid outcome, queue submissions return only a receipt, and no retry or polling is performed. It does not disclose what a successful synchronous response contains, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short clauses, front-loaded with the core action and payment/validation context before failure-mode caveats; dense but largely waste-free. The 'do not invent fields or choose a default' clause partially restates the required-parameter constraint already visible in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paid, destructive, open-world synchronous tool with no output schema, the description supplies the critical context: payment, no retry/polling, queue-vs-sync distinction, and timeout ambiguity. It stops short of describing the success payload or the confirm/account prerequisites, but the schema and annotations cover those adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across 6 parameters (including nested lifecycle objects), so the schema already documents model_id, input, confirm, store_io and lifecycle semantics. The description reinforces that model_id/input must be exact and not guessed, but adds no syntax, format or mapping detail beyond what the schema states, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (paid model request, run synchronously) with concrete scope: exact model_id/input, validation against the fetched native schema, no invented fields or defaults. It hints at the sibling split ('Queue submissions return receipt only') but never names submit_job/submit_generation_batch/generate_image, so the agent must infer which async alternative to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage conditions (only after native input-schema validation, only when the request is confirmed paid) and rules out retry/polling behavior, which is genuine guidance. However there is no explicit when-to-use-this-vs-siblings statement, and no stated prerequisites such as account/confirm requirements beyond what the schema already shows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world behavior, so the bar is lower. The description adds real value beyond them: optional API key for higher rate limits, cursor-based pagination, and how `limit` interacts with query/expansion. It does not describe what happens on invalid IDs or the error model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the three modes, which is exactly the right ordering, and headings make it scannable. It loses a point for mild redundancy against the schema (expansion values, endpoint_id examples appear twice) and a 'Common Use Cases' block that is largely restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does enough by describing the paginated list shape, minimal metadata, and the expanded fields. Missing pieces are return-value details for find/search modes and error behavior, but for a read-only discovery endpoint this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description goes beyond it with concrete `endpoint_id` examples, the 1-50 array limit, the interaction between `endpoint_id` and search params, and the expansion field semantics. It edges above baseline by adding mode-based interpretation the schema does not spell out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ("discovering model endpoints") and enumerates three distinct operating modes, so an agent immediately understands the tool's surface. It falls short of a 5 because it never differentiates itself from the sibling `get_model_info`, which plausibly overlaps with the 'Find Mode' by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is genuinely mapped to parameters: no params = list, `endpoint_id` = find, search params = filter. It also notes `expand` conditions and auth context. However, it names no alternative tool (e.g., `get_model_info` or `run_model`) so the agent has no cross-tool routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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.
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.
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.
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.
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.
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 tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds one genuinely non-obvious behavior — unresolved request/vector references are materialized into an asset before tags are applied — which is real value beyond the annotations. However it omits the most consequential behavioral fact for a destructive tool: that the supplied tag set fully replaces existing tags (that detail lives only in the schema's tag_ids description).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler; the action and its prerequisite are front-loaded. It is slightly under-specified for a tool with a nested union body rather than padded, so it reads as efficient rather than wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter destructive tool with a nested union body, the description covers the action and the reference-materialization side effect but leaves the replacement semantics, the three mutually exclusive body forms, and the confirm/idempotency parameters entirely to the schema. Adequate, but not complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 contributes one useful constraint not encoded in the schema (either request_id or vector_id must be supplied, since the schema marks nothing required), but it says nothing about the payload vs. flat-flag vs. payload_file union, the confirm gate, or the idempotency key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear verb+resource ('Set tags for an asset') and names the identifier inputs, but it never distinguishes this full-replacement operation from the many closely named siblings (assign_asset_tag, unassign_asset_tag, update_asset_tag, set_asset_tags_for_asset). An agent seeing 'Set tags' next to 'Assign asset tag' has to open both schemas to know which one replaces versus appends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states an input precondition ('Provide a request ID or vector ID') but gives no when-to-use guidance and no exclusions relative to the sibling tag tools. Nothing tells the agent when this tool is the right choice versus assign_asset_tag or unassign_asset_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. | |
| rules | No | ||
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the auth requirement (API key needs `assets:write`), the silent-drop behavior for rules referencing nonexistent users, and the fact that the response reflects the ACL actually applied so callers should verify it. These are exactly the failure modes an agent needs for a destructive, non-idempotent write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then progressively deeper detail, ending with a clearly bolded Authentication line. Every sentence carries information, though the default/rules explanation partially restates what the schema enum descriptions already convey.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter destructive mutation with nested objects and no output schema, the description covers the important operational facts: auth scope, silent rule dropping, and the need to verify the returned ACL. It omits guidance on confirm/account/payload_file, but those are documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 86%, so the baseline is 3, but the description adds real semantic value: the default/rules interplay ('allow with no rules makes the file public; forbid or hide restricts it to the rules you provide') and that rule users may be a nickname or user ID. The confirm/account/payload_file parameters are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Replaces the Access Control List of a fal CDN file.' It is clearly distinct from the read-side sibling get_storage_file_acl by the word 'Replaces', though it never names the sibling explicitly or states that it is the write counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the semantics of replacement and the explanation of what each default decision does. There is no explicit 'use this when...' guidance, no mention of get_storage_file_acl as the read alternative, and no statement of prerequisites beyond the auth note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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) |
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. The description adds genuinely new context beyond that: the assets:read permission requirement, the authentication requirement, and the 7-day validity ceiling on the generated signature. It never explains why a signing operation is flagged destructive (the required output_file write), which is the one notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short blocks, front-loaded with the core action and scope before the validity constraint and auth note. Every sentence carries information; only the parenthetical restatement of the 7-day limit is mildly redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 and no output schema, the description covers the essentials: what it produces, its ACL-bypassing behavior, validity window, and auth/permission requirements. It leaves the output_file contract and the destructive write side-effect implicit, relying on the schema to convey them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so url, account, confirm, payload, payload_file, output_file and expiration_seconds are all documented in the schema itself. The description only echoes the expiration_seconds 7-day cap, adding nothing about the payload vs. flat-flag mutual exclusion or the confirm flag's meaning. Baseline 3 applies 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.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Creates a signed URL') and resource ('fal CDN file') plus the key behavioral distinction 'regardless of its ACL'. This clearly separates it from siblings like get_storage_file_acl and set_storage_file_acl, which inspect or mutate ACLs rather than mint access credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Useful for sharing access-restricted files' gives a concrete when-to-use context, which is the main reason an agent would pick this over the ACL siblings. It does not name an explicit alternative or state exclusions (e.g., that ACL changes should use set_storage_file_acl instead), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| review_sha256 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Rich disclosure beyond annotations: refetch schemas/quotes and validate before the first paid request, refuse changed hash, submit sequentially, stop on first failure, report request IDs/failed and unattempted indices. It also explicitly enumerates what does NOT happen (no polling, retries, rollback, continuation, or budget guarantee), which aligns with the destructive/non-idempotent annotations and fills in failure semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action ('Confirmed one-to-ten async jobs'), then failure/validation behavior. Very dense and mostly telegraphic, with a few run-on clauses, but every sentence carries load and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains what the agent gets back (known request IDs, failed and unattempted indices), how failures propagate, and the pre-submission validation flow. For a destructive batch-submit tool this is complete enough to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the schema documents most fields. The description still adds cross-parameter meaning: 'refuse changed hash' ties review_sha256 to a gate condition, and 'one-to-ten' plus 'before first paid submission' explain how tasks interact with validation. This is genuine added semantics over the pattern/enum constraints in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: submitting a reviewed async generation batch of one-to-ten jobs. The phrase 'before first paid submission' and 'refuse changed hash' make clear it is the paid execution step following a preview, though it never names preview_generation_batch as the sibling counterpart. An agent can identify the action but must infer the preview relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Confirmed one-to-ten async jobs' and the confirm field ('Set true only when the user asked for exactly this action') imply the precondition of prior review, but the description never explicitly states when to prefer this over preview_generation_batch, submit_job, or run_model. 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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=false, openWorldHint=true, yet the description goes further: it is a PAID request, queue submissions return a receipt only, a synchronous timeout can leave an unknown paid outcome, and there is no retry or polling. This is exactly the consequence-level context an agent needs before spending money.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded, leading with the purpose and payment nature before caveats. Some phrasing ('image/video commands do not invent fields') is terse to the point of ambiguity, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a costly mutation tool with no output schema, the description adequately covers the risk profile, payment semantics, and outcome uncertainty. It does not describe the receipt shape, but that is a minor omission given the strong behavioral coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds real semantic weight: model_id and input must be EXACT, no default is chosen, and no fields are invented for image/video commands. That reinforces the two required parameters beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Confirmed paid model request', 'submitting a queued job') and the scope is discernible. However, it never names or distinguishes itself from close siblings like run_model, generate_image, generate_video, or submit_generation_batch, so an agent must infer the boundary from the 'queue' vs convenience-command framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: submit only when the user asked for exactly this action (confirm), using exact model_id/input, and image/video commands should not be used to fabricate fields. There is no explicit when-to-use/when-not statement and no named alternative tool, so guidance stays informal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unassign a tag from an asset by request ID or vector ID.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Tag ID | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the full safety profile (destructiveHint=true, idempotentHint=false, readOnlyHint=false), so the description only needs to add context beyond that. It adds none: it does not explain what gets destroyed, whether the confirm parameter gates execution, or the effect on existing tags, leaving the mutation behavior undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, short, front-loaded sentence with zero filler. The purpose is delivered immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with 8 parameters, a nested payload union, a confirm gate, and no output schema, this one-line description is too thin. It never addresses the confirm workflow, idempotency expectations, or how the body/payload alternatives relate, leaving real gaps despite the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, making 3 the baseline. The description's 'request ID or vector ID' loosely maps to the optional vector_id/request_id fields but omits the required tag_id and adds no syntax beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Unassign') and resource ('a tag from an asset'), which cleanly distinguishes it from the opposite operation assign_asset_tag. However, 'by request ID or vector ID' describes asset identification rather than the required tag_id, which slightly muddies what the tool actually acts on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no when-to-use guidance and never names the counterpart tool (assign_asset_tag) or the set_asset_tags_for_asset alternative. An agent must infer the correct context for calling this versus sibling tag operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unfavorite an asset by request ID or vector ID.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 beyond that: it does not state that the removal is a mutation of persistent state, whether it is reversible, or that confirm must be explicitly set. With zero annotation contradiction but no added context, a 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence, front-loaded with the verb and resource, with no padding. It is efficient but arguably too terse for a seven-parameter destructive tool, so not a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world mutation with seven parameters, a nested union body, and no output schema, the description is far too thin. It never explains that at least one identifier or payload must be supplied, how the body input modes are mutually exclusive, or what confirm guards against.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters (including the nested payload union and payload_file exclusivity rules) are already documented in the schema. The description only echoes the two identifier options, adding no syntax or mutual-exclusivity detail 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.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (unfavorite) and resource (asset) plus the two identifier forms it accepts. It is clearly separable from favorite_asset, though it does not explicitly distinguish itself from the near-identical unfavorite_asset_collection and unfavorite_asset_character siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names accepted identifiers but gives no when-to-use guidance, no prerequisites, and no routing between the three unfavorite variants or between request_id and vector_id. The only actionable instruction (confirm=true) lives in the schema, not here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unfavorite an asset character for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| character_id | Yes | Character collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
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. However, the description adds nothing beyond restating the title, and it leaves a real ambiguity: with destructiveHint=true, an agent may reasonably wonder whether this removes the character itself rather than just the favorite marking. Clarifying that only the favorite status is removed would have been valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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 is part of why guidance and behavioral context are missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 no output schema, the annotations carry the safety profile and the schema fully documents the parameters, so the description is minimally sufficient. It still omits what the confirm parameter implies about user intent verification and what happens if the character was not favorited, leaving the destructiveHint ambiguity unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the four parameter descriptions are substantive (e.g. account is a 'private account key profile label', confirm is 'set true only when the user asked for exactly this action'). The description contributes no additional 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (unfavorite) and a specific resource (asset character), and scopes it to the authenticated user's fal Assets library. It is clearly distinguishable from the collection/asset variants (unfavorite_asset, unfavorite_asset_collection), though it never explicitly references the inverse sibling favorite_asset_character.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 the obvious alternative (favorite_asset_character) or the generic unfavorite_asset. The agent must infer that this is the inverse of a favorite operation on the same entity type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unfavorite an asset collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| collection_id | Yes | Collection ID | |
| Idempotency_Key | No | Optional idempotency key for safe request retries |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is available structurally. The description adds nothing beyond the name: it does not say whether the unfavorite is reversible, what the 'confirm' parameter gates, or how retries behave despite the exposed Idempotency_Key. With annotations present the bar is lower, but this description contributes almost no extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the verb and scope front-loaded and zero filler. It is efficiently written but minimal rather than information-dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool, the annotations cover the safety profile and the schema fully documents all four parameters, so the essentials are present. The description itself is thinner than ideal for a destructive-leaning operation but does not leave an agent unable to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the non-obvious 'account' and 'confirm' semantics, so the schema carries the full burden. The description adds no parameter detail beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 collection') and scopes it to the authenticated user's fal Assets library. It never distinguishes itself from the inverse sibling favorite_asset_collection or the nearby unfavorite_asset/favorite_asset_character tools, so the agent must infer the pairing from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, and the obvious alternative (favorite_asset_collection) is not named. The only routing signal is the verb in the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Character display name | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| description | No | Text description used for character semantic matching | |
| character_id | Yes | Character collection ID | |
| payload_file | No | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. | |
| Idempotency_Key | No | Optional idempotency key for safe request retries | |
| cover_image_url | No | Optional fal-hosted cover image URL for the character | |
| reference_images | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered. The description adds one useful behavioral note (unresolved ID references are materialized before character state is added) but is silent on partial-update semantics, the confirm flag's role, and idempotency-key behavior, leaving notable mutation behavior unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the purpose front-loaded and no filler. The reference-images clause is dense but earns its place given the ambiguity between IDs and URLs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter, destructive mutation with nested objects and no output schema, the description covers purpose and reference-image semantics but omits the confirm flag, idempotency usage, and the exclusivity between payload, payload_file, and flat flags. The rich schema compensates, but the description is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 90%, so the schema already documents nearly every parameter, and the description's reference_images sentence is essentially duplicated verbatim from the schema. No additional meaning is added for character_id, confirm, account, payload, or the flat-vs-payload mutual exclusion; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Update) and resource (asset character) within the fal Assets library, which cleanly separates it from create_asset_character and delete_asset_character. It does not name those siblings explicitly, so an agent must infer the boundary from the verb alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives real guidance for one parameter family (prefer vector/request IDs over URLs for reference_images), which is genuine when-to-use advice. However, it offers no guidance on when to update versus creating a new character, no prerequisites, and no mention of the mutually exclusive body forms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update asset collection for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| 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 |
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 covered structurally. The description adds nothing on top of that — it doesn't say whether this is a partial merge or a full replace of existing collection fields, what is lost on update, or how account scoping affects the target collection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler or repetition. It is efficient, though its brevity is partly under-specification rather than disciplined concision for a 12-parameter destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters, nested objects, a three-way union body, a confirm gate, and a destructive mutation flag, one sentence with no output schema leaves major gaps: what changes, whether unspecified fields are cleared, and what the response/state looks like afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 12 parameters, including the mutually exclusive payload / flat-body / payload_file union and the confirm gate, so the schema carries the parameter burden. The description never mentions any parameter, so baseline 3 is the correct ceiling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ("Update asset collection") and scopes it to the authenticated user's fal Assets library. However, it does nothing to distinguish this from the many sibling collection mutators (create_asset_collection, delete_asset_collection, move_asset_collection, favorite_asset_collection), so an agent must infer the difference from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of alternatives for modifying a collection, and no statement of prerequisites or the conditions under which a destructive update is appropriate. The presence of a "confirm" gate and a destructiveHint=true annotation makes this omission more costly, since the agent gets no routing logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update asset tag for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
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 essentially nothing on top: it never says what is modified, whether the change is reversible, or how the confirm and Idempotency_Key parameters behave. No contradiction with annotations, but no added value either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero padding — the verb and resource lead. It is lean and readable, though arguably undersized for a destructive tool with seven parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with seven parameters, a nested payload object, a confirm gate, and no output schema, one generic sentence is not enough. Nothing tells the agent which fields are updatable, what the confirm requirement means in practice, or what happens on failure — the annotations carry the entire behavioral load.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 seven parameters including the payload/payload_file mutual exclusion and the confirm flag. The description adds no syntax, format, or interpretation detail beyond the schema, which is the baseline 3 under high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a verb+resource ('Update asset tag') plus a scope ('the authenticated user's fal Assets library'), but 'Update asset tag' largely restates the tool name and title. It does nothing to separate this from close siblings such as create_asset_tag, delete_asset_tag, assign_asset_tag, or set_asset_tags_for_asset, so an agent must open the schema to know which tag operation applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative-tool guidance at all. With four or five tag-related siblings in the list, the absence of any routing hint (e.g., use this to rename a tag, use assign_asset_tag to attach one) leaves selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| initial_acl | No | ||
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructiveHint/readOnlyHint/idempotentHint/openWorldHint) by disclosing full-replacement semantics, that null clears to system default, that ACL rules for non-existent users are silently dropped, that the response reflects only what was saved, and the required auth permission account:settings:write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core replace operation, then the destructive null-clearing warning, then edge-case behavior, then the header relationship, then auth. Every sentence carries non-redundant operational information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, nested-body mutation with no output schema, the description covers the destructive semantics, the required auth scope, and what the response contains. An agent has everything needed to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 83% (baseline 3), but the description adds meaningful semantics the schema does not: null/omitted fields reset to default, so a full configuration must be sent, and invalid-user ACL rules are dropped on save. These materially change how the caller populates the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (replaces) and resource (account-level storage lifecycle settings applied to newly uploaded fal CDN files), with scope qualifiers ('account-level', 'newly uploaded') that distinguish it from the per-file ACL siblings (set_storage_file_acl, get_storage_file_acl). An agent can tell what it configures 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives strong invocation guidance ('always send the full desired configuration' because omitted/null fields are cleared) and explains the relationship to the per-request header. However, it never states when to use this vs alternatives such as get_storage_settings (read) or set_storage_file_acl (per-file), so routing between siblings 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.
Upload asset for the authenticated user's fal Assets library.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Set true only when the user asked for exactly this action. | |
| payload | No | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the safety profile is covered by structured data. The description adds nothing behavioral: it does not explain idempotency/retry semantics for the exposed Idempotency_Key, what the confirm flag gates, or what happens to account/library state on success.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, front-loading the verb and target. It is efficient, though its brevity reflects under-specification rather than disciplined trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool: 11 params, a nested payload object, three mutually exclusive body-input forms (flat flags vs payload vs payload_file), and no output schema. The description explains none of that, nor the confirm/idempotency semantics, leaving real gaps for an agent to resolve on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 11 parameters including the nested payload object and mutual-exclusion rules are documented in the schema itself. The description adds no extra meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (upload) and resource target (asset in the fal Assets library) for the authenticated user, which is clearer than a bare 'upload'. However, it never distinguishes this from the sibling upload_file, which presumably targets storage rather than the asset library, so the agent must 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.
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 despite sibling overlap with upload_file, create_asset_character, and collection-assignment tools. The agent gets no signal about which upload path to pick or when this is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Exact configured isolated API-key profile label. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description adds genuinely useful mechanics beyond that: a pinned SDK upload-initiation step followed by a credential-free HTTPS PUT with redirects refused, and explicitly no multipart retries or automatic generation, which contextualizes the non-idempotent, non-retrying behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the input constraints are front-loaded. It is telegraphic and jargon-dense, but nothing is wasted and the structure is functional.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 carries the return-value burden and it says nothing about what an upload produces or how it relates to upload_asset. For a destructive, non-idempotent mutation with nested lifecycle parameters, the description is serviceable but leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, including the file size/symlink constraints and lifecycle semantics. The description largely restates the file constraints and adds no meaning for confirm, account, or content_type. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that a local file is uploaded through a specific protocol, but it opens with a noun phrase of constraints rather than a clean verb+resource statement. It never distinguishes itself from the sibling upload_asset, leaving the agent to guess which upload tool applies. Purpose is inferable but not crisply stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing sentence lists exclusions ('no remote URL ingestion, base64 model output, multipart retries or automatic generation'), which implicitly tells the agent when this tool is not appropriate. However, it names no alternative tool and gives no positive when-to-use condition beyond the input constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.0.1add_asset_to_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."assign_asset_tag1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."cancel_job1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."create_asset_character14 fields changedInput schema / $defsAdded value: +{
+ "reference_images": {
+ "description": "Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array"
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / payload / properties / reference_images / $refAdded value: +"#/$defs/reference_images"Input schema / properties / payload / properties / reference_images / descriptionRemoved value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."Input schema / properties / payload / properties / reference_images / itemsRemoved value: -{
- "minLength": 1,
- "type": "string"
-}Input schema / properties / payload / properties / reference_images / maxItemsRemoved value: -20Input schema / properties / payload / properties / reference_images / minItemsRemoved value: -1Input schema / properties / payload / properties / reference_images / typeRemoved value: -"array"Input schema / properties / reference_images / $refAdded value: +"#/$defs/reference_images"Input schema / properties / reference_images / descriptionRemoved value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."Input schema / properties / reference_images / itemsRemoved value: -{
- "minLength": 1,
- "type": "string"
-}Input schema / properties / reference_images / maxItemsRemoved value: -20Input schema / properties / reference_images / minItemsRemoved value: -1Input schema / properties / reference_images / typeRemoved value: -"array"create_asset_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."create_asset_tag1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."create_workflow12 fields changedInput schema / $defsAdded value: +{
+ "contents": {
+ "description": "The workflow definition/configuration object",
+ "properties": {
+ "metadata": {
+ "additionalProperties": {},
+ "description": "Optional workflow metadata",
+ "type": "object"
+ },
+ "name": {
+ "description": "Internal name of the workflow definition",
+ "type": "string"
+ },
+ "nodes": {
+ "additionalProperties": {
+ "additionalProperties": {},
+ "type": "object"
+ },
+ "description": "Workflow nodes keyed by node id",
+ "type": "object"
+ },
+ "output": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Output field mappings keyed by output name",
+ "type": "object"
+ },
+ "schema": {
+ "description": "Input/output schema for the workflow",
+ "properties": {
+ "input": {
+ "additionalProperties": {},
+ "description": "Input fields schema",
+ "type": "object"
+ },
+ "output": {
+ "additionalProperties": {},
+ "description": "Output fields schema",
+ "type": "object"
+ }
+ },
+ "required": [
+ "input",
+ "output"
+ ],
+ "type": "object"
+ },
+ "version": {
+ "description": "Workflow definition format version",
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "version",
+ "nodes",
+ "output",
+ "schema"
+ ],
+ "type": "object"
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / contents / $refAdded value: +"#/$defs/contents"Input schema / properties / contents / descriptionRemoved value: -"The workflow definition/configuration object"Input schema / properties / contents / propertiesRemoved value: -{
- "metadata": {
- "additionalProperties": {},
- "description": "Optional workflow metadata",
- "type": "object"
- },
- "name": {
- "description": "Internal name of the workflow definition",
- "type": "string"
- },
- "nodes": {
- "additionalProperties": {
- "additionalProperties": {},
- "type": "object"
- },
- "description": "Workflow nodes keyed by node id",
- "type": "object"
- },
- "output": {
- "additionalProperties": {
- "type": "string"
- },
- "description": "Output field mappings keyed by output name",
- "type": "object"
- },
- "schema": {
- "description": "Input/output schema for the workflow",
- "properties": {
- "input": {
- "additionalProperties": {},
- "description": "Input fields schema",
- "type": "object"
- },
- "output": {
- "additionalProperties": {},
- "description": "Output fields schema",
- "type": "object"
- }
- },
- "required": [
- "input",
- "output"
- ],
- "type": "object"
- },
- "version": {
- "description": "Workflow definition format version",
- "type": "string"
- }
-}Input schema / properties / contents / requiredRemoved value: -[
- "name",
- "version",
- "nodes",
- "output",
- "schema"
-]Input schema / properties / contents / typeRemoved value: -"object"Input schema / properties / payload / properties / contents / $refAdded value: +"#/$defs/contents"Input schema / properties / payload / properties / contents / descriptionRemoved value: -"The workflow definition/configuration object"Input schema / properties / payload / properties / contents / propertiesRemoved value: -{
- "metadata": {
- "additionalProperties": {},
- "description": "Optional workflow metadata",
- "type": "object"
- },
- "name": {
- "description": "Internal name of the workflow definition",
- "type": "string"
- },
- "nodes": {
- "additionalProperties": {
- "additionalProperties": {},
- "type": "object"
- },
- "description": "Workflow nodes keyed by node id",
- "type": "object"
- },
- "output": {
- "additionalProperties": {
- "type": "string"
- },
- "description": "Output field mappings keyed by output name",
- "type": "object"
- },
- "schema": {
- "description": "Input/output schema for the workflow",
- "properties": {
- "input": {
- "additionalProperties": {},
- "description": "Input fields schema",
- "type": "object"
- },
- "output": {
- "additionalProperties": {},
- "description": "Output fields schema",
- "type": "object"
- }
- },
- "required": [
- "input",
- "output"
- ],
- "type": "object"
- },
- "version": {
- "description": "Workflow definition format version",
- "type": "string"
- }
-}Input schema / properties / payload / properties / contents / requiredRemoved value: -[
- "name",
- "version",
- "nodes",
- "output",
- "schema"
-]Input schema / properties / payload / properties / contents / typeRemoved value: -"object"delete_asset_character1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."delete_asset_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."delete_asset_tag1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."delete_request_payloads1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."favorite_asset1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."favorite_asset_character1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."favorite_asset_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."generate_image1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."generate_video1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."move_asset_collection10 fields changedInput schema / $defsAdded value: +{
+ "parent_collection_id": {
+ "description": "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,
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / parent_collection_id / $refAdded value: +"#/$defs/parent_collection_id"Input schema / properties / parent_collection_id / descriptionRemoved value: -"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."Input schema / properties / parent_collection_id / minLengthRemoved value: -1Input schema / properties / parent_collection_id / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / payload / properties / parent_collection_id / $refAdded value: +"#/$defs/parent_collection_id"Input schema / properties / payload / properties / parent_collection_id / descriptionRemoved value: -"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."Input schema / properties / payload / properties / parent_collection_id / minLengthRemoved value: -1Input schema / properties / payload / properties / parent_collection_id / typeRemoved value: -[
- "string",
- "null"
-]remove_asset_from_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."run_model1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."set_asset_tags_for_asset1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."set_storage_file_acl12 fields changedInput schema / $defsAdded value: +{
+ "rules": {
+ "default": [],
+ "description": "User-specific overrides to the default decision",
+ "items": {
+ "additionalProperties": false,
+ "description": "A per-user access control rule",
+ "properties": {
+ "decision": {
+ "description": "Access decision applied to this user",
+ "enum": [
+ "allow",
+ "forbid",
+ "hide"
+ ],
+ "type": "string"
+ },
+ "user": {
+ "description": "User nickname or user ID the rule applies to",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "user",
+ "decision"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / payload / properties / rules / $refAdded value: +"#/$defs/rules"Input schema / properties / payload / properties / rules / defaultRemoved value: -[]Input schema / properties / payload / properties / rules / descriptionRemoved value: -"User-specific overrides to the default decision"Input schema / properties / payload / properties / rules / itemsRemoved value: -{
- "additionalProperties": false,
- "description": "A per-user access control rule",
- "properties": {
- "decision": {
- "description": "Access decision applied to this user",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "user": {
- "description": "User nickname or user ID the rule applies to",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "user",
- "decision"
- ],
- "type": "object"
-}Input schema / properties / payload / properties / rules / typeRemoved value: -"array"Input schema / properties / rules / $refAdded value: +"#/$defs/rules"Input schema / properties / rules / defaultRemoved value: -[]Input schema / properties / rules / descriptionRemoved value: -"User-specific overrides to the default decision"Input schema / properties / rules / itemsRemoved value: -{
- "additionalProperties": false,
- "description": "A per-user access control rule",
- "properties": {
- "decision": {
- "description": "Access decision applied to this user",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "user": {
- "description": "User nickname or user ID the rule applies to",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "user",
- "decision"
- ],
- "type": "object"
-}Input schema / properties / rules / typeRemoved value: -"array"sign_storage_file_url1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."submit_generation_batch1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."submit_job1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."unassign_asset_tag1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."unfavorite_asset1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."unfavorite_asset_character1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."unfavorite_asset_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."update_asset_character14 fields changedInput schema / $defsAdded value: +{
+ "reference_images": {
+ "description": "Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array"
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / payload / properties / reference_images / $refAdded value: +"#/$defs/reference_images"Input schema / properties / payload / properties / reference_images / descriptionRemoved value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."Input schema / properties / payload / properties / reference_images / itemsRemoved value: -{
- "minLength": 1,
- "type": "string"
-}Input schema / properties / payload / properties / reference_images / maxItemsRemoved value: -20Input schema / properties / payload / properties / reference_images / minItemsRemoved value: -1Input schema / properties / payload / properties / reference_images / typeRemoved value: -"array"Input schema / properties / reference_images / $refAdded value: +"#/$defs/reference_images"Input schema / properties / reference_images / descriptionRemoved value: -"Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images."Input schema / properties / reference_images / itemsRemoved value: -{
- "minLength": 1,
- "type": "string"
-}Input schema / properties / reference_images / maxItemsRemoved value: -20Input schema / properties / reference_images / minItemsRemoved value: -1Input schema / properties / reference_images / typeRemoved value: -"array"update_asset_collection1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."update_asset_tag1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."update_storage_settings14 fields changedInput schema / $defsAdded value: +{
+ "initial_acl": {
+ "additionalProperties": false,
+ "description": "Default ACL applied to newly uploaded files. Null uses the system default (public).",
+ "properties": {
+ "default": {
+ "description": "Fallback decision when no user-specific rule matches",
+ "enum": [
+ "allow",
+ "forbid",
+ "hide"
+ ],
+ "type": "string"
+ },
+ "rules": {
+ "default": [],
+ "description": "User-specific overrides to the default decision",
+ "items": {
+ "additionalProperties": false,
+ "description": "A per-user access control rule",
+ "properties": {
+ "decision": {
+ "description": "Access decision applied to this user",
+ "enum": [
+ "allow",
+ "forbid",
+ "hide"
+ ],
+ "type": "string"
+ },
+ "user": {
+ "description": "User nickname or user ID the rule applies to",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "user",
+ "decision"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "default"
+ ],
+ "type": [
+ "object",
+ "null"
+ ]
+ }
+}Input schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."Input schema / properties / initial_acl / $refAdded value: +"#/$defs/initial_acl"Input schema / properties / initial_acl / additionalPropertiesRemoved value: -falseInput schema / properties / initial_acl / descriptionRemoved value: -"Default ACL applied to newly uploaded files. Null uses the system default (public)."Input schema / properties / initial_acl / propertiesRemoved value: -{
- "default": {
- "description": "Fallback decision when no user-specific rule matches",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "rules": {
- "default": [],
- "description": "User-specific overrides to the default decision",
- "items": {
- "additionalProperties": false,
- "description": "A per-user access control rule",
- "properties": {
- "decision": {
- "description": "Access decision applied to this user",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "user": {
- "description": "User nickname or user ID the rule applies to",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "user",
- "decision"
- ],
- "type": "object"
- },
- "type": "array"
- }
-}Input schema / properties / initial_acl / requiredRemoved value: -[
- "default"
-]Input schema / properties / initial_acl / typeRemoved value: -[
- "object",
- "null"
-]Input schema / properties / payload / properties / initial_acl / $refAdded value: +"#/$defs/initial_acl"Input schema / properties / payload / properties / initial_acl / additionalPropertiesRemoved value: -falseInput schema / properties / payload / properties / initial_acl / descriptionRemoved value: -"Default ACL applied to newly uploaded files. Null uses the system default (public)."Input schema / properties / payload / properties / initial_acl / propertiesRemoved value: -{
- "default": {
- "description": "Fallback decision when no user-specific rule matches",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "rules": {
- "default": [],
- "description": "User-specific overrides to the default decision",
- "items": {
- "additionalProperties": false,
- "description": "A per-user access control rule",
- "properties": {
- "decision": {
- "description": "Access decision applied to this user",
- "enum": [
- "allow",
- "forbid",
- "hide"
- ],
- "type": "string"
- },
- "user": {
- "description": "User nickname or user ID the rule applies to",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "user",
- "decision"
- ],
- "type": "object"
- },
- "type": "array"
- }
-}Input schema / properties / payload / properties / initial_acl / requiredRemoved value: -[
- "default"
-]Input schema / properties / payload / properties / initial_acl / typeRemoved value: -[
- "object",
- "null"
-]upload_asset1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."upload_file1 field changedInput schema / properties / confirm / descriptionPrevious value: -"Explicit approval for the requested paid work, mutation, upload or private file."New value: +"Set true only when the user asked for exactly this action."v2.0.0add_asset_to_collectionassign_asset_tagcancel_jobcreate_asset_charactercreate_asset_collectioncreate_asset_tagcreate_workflowdelete_asset_characterdelete_asset_collectiondelete_asset_tagdelete_request_payloadsestimate_pricingfavorite_assetfavorite_asset_characterfavorite_asset_collectiongenerate_imagegenerate_videoget_account_billingget_analyticsget_assetget_asset_characterget_asset_collectionget_asset_collection_hierarchyget_asset_lineageget_billing_eventsget_job_resultget_job_statusget_model_infoget_operation_schemaget_organization_teamsget_organization_usageget_pricingget_storage_file_aclget_storage_settingsget_usageget_workflowlist_accountslist_asset_characterslist_asset_collection_assetslist_asset_collectionslist_asset_tagslist_asset_tags_for_assetlist_assetslist_requests_by_endpointlist_workflowsmove_asset_collectionpreview_generation_batchremove_asset_from_collectionrun_modelsearch_modelssearch_requestsset_asset_tags_for_assetset_storage_file_aclsign_storage_file_urlsubmit_generation_batchsubmit_jobunassign_asset_tagunfavorite_assetunfavorite_asset_characterunfavorite_asset_collectionupdate_asset_characterupdate_asset_collectionupdate_asset_tagupdate_storage_settingsupload_assetupload_fileScored across 66 tools
run_model, submit_job, generate_image, and generate_video share byte-identical descriptions ('Confirmed paid model request after current native input-schema validation...'), so an agent cannot tell which to pick. There is also overlap among estimate_pricing/get_pricing and get_usage/get_billing_events/get_account_billing, though most asset, storage, and workflow tools are distinct.
Nearly every tool follows a clean verb_noun snake_case pattern (get_asset, create_asset_collection, delete_asset_tag, list_asset_characters, set_storage_file_acl). Even the generation and job tools (run_model, submit_job, cancel_job, preview_generation_batch) fit the same convention, with no camelCase or mixed styles.
66 tools far exceeds a well-scoped surface and crosses the extreme-mismatch threshold. The count is inflated by near-duplicate generation tools (run_model/submit_job/generate_image/generate_video) and a sprawling asset API, making the set unwieldy for an agent to navigate.
Coverage is broad and genuinely deep: full CRUD for asset collections, characters, and tags; billing, usage, analytics, storage ACL/lifecycle, jobs, requests, and organization endpoints. The main gap is workflows, which support list/create/get but no update or delete, leaving a lifecycle dead end.
Account, billing, team, API key and model discovery tools for agents that use ModelsLab.
Generate AI video, images and music. Browse models and prices; OAuth and one prepaid balance.
Generate AI video, images and music. Browse models and prices; OAuth and one prepaid balance.
Generate AI images and videos, quote credit costs, manage media and track batch jobs with OAuth.