Personal asset search engine: everything you make or upload is searchable by what's inside it.
Scored across 27 tools
Most tools have clearly distinct purposes, and the descriptions actively disambiguate (e.g. generate_sheet explicitly says never call generate_image for a sheet; cutout vs get_cutout split create/fetch; scan_image vs get_detections split run/read). The one soft spot is the cluster of image-producing tools (generate_image, restyle, expand_image, upscale_image, generate_sheet) where an agent must read carefully to pick correctly, though each is well delineated.
The dominant pattern is consistent snake_case verb_noun (generate_image, list_assets, get_task, delete_asset, cancel_task). A few deviations exist — bare verbs like restyle, search, cutout, and the noun-style sheet_options and whoami — but overall the convention is predictable and readable.
27 tools is on the heavy side and above the comfortable 3-15 range. The domain is genuinely broad (image/video generation, editing, sheets, assets, projects, tasks, search, pricing, account), so most tools earn their place, but the surface is dense enough to feel like a lot to navigate.
Coverage is strong across the creative lifecycle: generation, editing (restyle/expand/upscale/cutout), video, sprite sheets, asset/project management, async task control, detection-aware search, and pricing. Minor gaps remain — deletion is scoped to assets (no removal for generations or projects) and there's no explicit upload tool — but these are small workarounds.
Adds a remote image (by url), no AI. as:"reference" (default) = a reusable reference asset whose id goes into reference_asset_ids; as:"timeline" = a photo in a project's timeline (needs project_id); as:"product" = that project's product photos. metadata = your own fields (max 4 KB), returned on every read. The answer's versions lists other versions of the same picture already in the library (larger, smaller, same size): tell the user. Counts against storage.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | ||
| url | Yes | ||
| name | No | ||
| metadata | No | ||
| project_id | No |
Imports a video FILE from a link (a direct .mp4/.mov/.webm url, not a page that plays it), any size the user's storage allows. Runs in the background: returns a task_id; poll get_task until complete, when generation_id is the clip. density (quick|normal|detailed) also indexes it for search (clips up to 180 s, costs credits). metadata = your own fields (max 4 KB), returned on every read. The same file already in the project is not stored twice: the task completes with the existing clip. Counts against storage. Every clip gets a light 1080p editing copy, made in the background (counts toward storage; none when the file already is 1080p H.264). keep_original:false then drops the uploaded original to save space, but the clip is 1080p from then on; default keeps it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| name | No | ||
| prompt | No | ||
| density | No | ||
| metadata | No | ||
| project_id | No | ||
| keep_original | No |
Cancels a running task. Confirm with the user first; spent credits are not refunded.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds specific behavioral details: the need for user confirmation and the non-refundable credit policy. This goes beyond the annotation and helps the agent understand consequences.
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 that conveys the core action and critical caveats. No wasted words; the warning is front-loaded and impactful.
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 cancellation tool with one parameter and no output schema, the description covers the action, side effects, and user confirmation. It lacks details on return values, but that's acceptable given the simplicity and 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?
The single parameter task_id is self-explanatory, but the description does not explicitly explain its meaning or format. With 0% schema coverage, the description could have added a line like 'task_id is the ID of the running task to cancel,' but the name is clear enough.
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 clearly states the tool cancels a running task, with a specific verb and resource. It distinguishes from siblings like retry_task or get_task by specifying 'running task', implying it only applies to tasks in progress.
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 provides usage context: confirm with the user first and warns about non-refundable credits. It doesn't explicitly state when not to use it or mention alternatives, but the guidance is actionable for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subject cutout (transparent PNG + clean plate). COSTS CREDITS. Source: exactly one of generation_id, asset_id, or url.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| asset_id | No | ||
| project_id | No | ||
| generation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but do not disclose the cost implications. The description explicitly warns 'COSTS CREDITS', which is valuable beyond annotations. However, no other behavioral details (e.g., credits amount, processing time) are given, so a middle score 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?
The description is exceptionally concise, with two sentences that pack essential information: the output, the cost warning, and the source constraint. Every word serves a purpose, and critical constraints are front-loaded.
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 4 parameters with 0% schema coverage and no output schema, the description is somewhat incomplete. It explains the source constraint but not project_id's role or what the output 'clean plate' means practically. The cost warning is helpful but more context on expected behavior is needed for a full picture.
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%, meaning the schema provides no descriptions. The description mentions that exactly one of generation_id, asset_id, or url must be used, which adds meaning, but it does not clarify the purpose of project_id or the relationship between the three source parameters. This partially compensates for the schema gap but leaves gaps.
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 clearly states the tool's purpose ('subject cutout') and its output (transparent PNG + clean plate), but it does not explicitly distinguish itself from sibling tools like get_cutout or expand_image, which could be confused for similar operations.
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 a key usage guideline: exactly one of generation_id, asset_id, or url must be provided, which is crucial. However, it does not explain when to use cutout versus alternatives like expand_image or restyle, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes an asset. DESTRUCTIVE — confirm with the user first. If it is used somewhere (a quote, a share page) the call fails naming the places: show them, and only on the user's OK retry with force:true.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| asset_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint/readOnlyHint annotations by disclosing that deletion is permanent, that a confirmation step is mandated, that referential integrity causes an error naming the blocking quote or share page, and that force:true is the escalation path. This is the exact behavioral context an agent needs before a destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the destructive warning front-loaded, followed by the failure mode and the recovery path. Every clause carries actionable 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 two-parameter destructive tool with no output schema, the description covers the safety precondition, the error condition, and the retry semantics. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning; it fully explains the non-obvious `force` parameter by tying it to the failed-deletion scenario and the user-approval precondition. `asset_id` is left unaddressed, but its meaning is self-evident from the name.
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 ('Permanently deletes an asset') and the permanence qualifier immediately frames the operation's stakes. The delete verb cleanly separates it from siblings like get_asset and list_assets without needing to name them.
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 explicit operational guidance: confirm with the user first, and if the call fails because the asset is referenced, show the listed places and only retry with force:true on user approval. This is a clear conditional workflow, though it does not name an alternative tool for the referenced-asset case (e.g., removing the reference first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Outpaints an existing generation to a bigger canvas / new aspect ratio — the model extends the scene beyond the original edges. COSTS CREDITS (generate_* by output resolution). Creates a NEW generation in the source's own project. Optionally restrict directions with extend, or zoom out with zoom < 1. An uploaded asset works as the base too (asset_id, not both); its result goes to project_id or the asset's project.
| Name | Required | Description | Default |
|---|---|---|---|
| zoom | No | 0-1; below 1 zooms out (subject shrinks, more scene appears). | |
| extend | No | Directions to extend. Default: all four. | |
| asset_id | No | ||
| project_id | No | asset_id only. | |
| resolution | No | Default: the source's. | |
| generation_id | No | ||
| target_aspect_ratio | Yes |
Generates an AI image. COSTS CREDITS (call get_pricing: generate_* for Nano Banana 2.1, generate_pro_* for Nano Banana Pro, generate_gpt_* for GPT Image 2.5). Returns the image inline plus id and credits_remaining. Attach references with reference_asset_ids (up to 14). @slug in the prompt or entity_ids attach a saved entity's sheet (list_entities). Pick model for the job: Nano Banana 2.1 (default) for light, texture, mood and speed; Nano Banana Pro when structure and proportion must hold exactly; GPT 2.5 Flare for text you can actually read (labels, packaging, signs); GPT 2.5 Sunburst for the same with more care over references, slower. GPT tops out at 2K.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | gemini-nano-banana-2.1 = Nano Banana 2.1 (default), gemini-3-pro-image = Nano Banana Pro, gpt-image-2.5-flare = GPT 2.5 Flare, gpt-image-2.5-sunburst = GPT 2.5 Sunburst. | |
| prompt | Yes | Max 16000 chars. | |
| entity_ids | No | ||
| project_id | Yes | Required (no default on a hosted server). | |
| resolution | No | GPT Image 2.5 renders 1K and 2K only. | |
| aspect_ratio | No | ||
| reference_asset_ids | No | Up to 14. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (non-read-only, non-destructive), yet the description adds substantial behavioral context: the call costs credits, returns the image inline plus id and credits_remaining, reference limit of 14, entity attachment semantics, and a model-specific resolution ceiling. That is exactly the value-add expected beyond structured fields.
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 purpose and the credit cost, then packs model guidance efficiently into one paragraph. A couple of clauses (model alias list, "up to 14") restate the schema rather than adding information, which is minor waste but keeps it from 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 7-parameter mutation tool with no output schema, the description covers cost, return shape, reference mechanics, entity attachment, and model/resolution constraints. An agent has everything needed to invoke it correctly without opening other 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?
With 71% schema coverage, the description still earns credit for explaining entity_ids (which has no schema description) via @slug and saved-entity sheets, and for clarifying the model ecosystem by family. It duplicates the schema's alias mapping and the "up to 14" limit, and leaves aspect_ratio unexplained, so it falls short of full compensation.
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 ("Generates an AI image") and immediately differentiates itself from siblings like expand_image, restyle, and generate_video by describing image generation from a prompt with references. The model-selection sentence further sharpens what kind of generation this is.
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 explicit guidance on how to pick a model for the job (light/texture vs strict proportion vs readable text) and points to get_pricing for credits. It does not, however, tell the agent when to prefer this tool over sibling image mutators such as expand_image or restyle, so tool-level routing 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.
Makes ONE image holding several separate elements laid out so each can be cut out: an animation cycle, a sprite sheet, an icon set, stickers, props. COSTS CREDITS: one image at the planned tier; quote with dry_run:true first, free. The asserted count, the keyable ground, no lines or labels, a grid whose cells cut cleanly and cells big enough to use are all built here, so never write this prompt yourself and never call generate_image for a sheet. Pick by job:
An animation of one subject (a walk, a face laughing, a coin spinning): kind frames + sequences from sheet_options ({family, type, id, level}; smooth = an in-between after every drawing, the default) + subject + art_style (photograph, film-still, studio-portrait, render-3d, stop-motion for a real subject; inked-cel, anime-cel, watercolour and the rest for a drawn one).
Pixel-art game sprites: kind sprites + sequences by game type. No art_style: pixel art is the style.
Icons, stickers, props: kind + items, one short description each. @slug in subject or entity_ids attach a saved entity's sheet (list_entities). get_sheet_atlas then gives frame rects and tags for any engine.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | frames = animation, any subject real or drawn; sprites = 8/16-bit pixel art; icons, stickers, props = matched sets. | |
| items | No | One short description each, after any sequences. | |
| model | No | Default gemini-nano-banana-2.1 (Nano Banana 2.1). GPT stops at 2K. | |
| style | No | Your own words about the look, joined after art_style. | |
| ground | No | The value NOT in the artwork. Default black. | |
| dry_run | No | Quote only: nothing generated or charged. | |
| per_row | No | Override the planned columns. | |
| subject | No | Who or what is in every frame. Without it every sheet invents someone. | |
| art_style | No | A style id from sheet_options. Frames only. | |
| sequences | No | From sheet_options, in order; several stack on one sheet. | |
| style_ids | No | Pictures whose look to borrow (ids). | |
| entity_ids | No | ||
| project_id | No | ||
| resolution | No | Override the planned tier. | |
| prompt_only | No | Free: just the plan and prompt, for generate_image as given. | |
| reference_ids | No | Sheets of the same thing to match; for frames, the subject to keep. | |
| reference_note | No | What to take from the attached pictures, in your words. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false/destructiveHint=false; the description adds the crucial cost behavior (consumes credits, tier-dependent), the free dry_run quote path, and the guarantees baked in (asserted count, keyable ground, no lines/labels, clean-cut grid). This is behavioral context well beyond the structured fields.
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 and the cost warning, followed by a clearly structured job-selection guide. It is long, but for a 17-parameter tool nearly every clause carries actionable information; only minor tightening is possible.
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?
Covers the call lifecycle (quote → generate), dependencies, and per-kind usage for a complex schema with no output schema. Coverage of secondary params (project_id, model trade-offs) is thinner, but the agent has what it needs to invoke 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?
With 88% schema coverage the baseline is 3, but the description adds real semantic value: it explains the @slug syntax for subject/entity_ids, the level option semantics (smooth = an in-between, the default), art_style options for real vs drawn subjects, and that sequences come from sheet_options and stack on one sheet.
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 ('Makes ONE image holding several separate elements') and immediately names what it produces: animation cycles, sprite sheets, icon sets, stickers, props. It explicitly distinguishes itself from siblings by forbidding generate_image for a sheet and warning 'never write this prompt yourself'.
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?
Includes a dedicated 'Pick by job' section that maps each use case (animation, pixel-art sprites, icons/stickers/props) to the exact kind + sequences/items recipe. It also prescribes the cost-safe workflow ('quote with dry_run:true first, free') and names dependencies (sheet_options, get_sheet_atlas, list_entities).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Makes a video from an image the user owns. MOST EXPENSIVE: per second, charged on completion, purchased credits only. Async: poll get_task. Quote with dry_run:true (free), confirm with the user. Pick by job (credits/s, std/pro):
Still to life: kling-v3. 120/160; sound +40; 4K 600; 3-15s; end_frame_id.
Cheapest with sound: veo-3.1-lite-generate-preview. 4/6/8s; 8s = 280 (1080p 440); end_frame_id.
Keep a clip's acting, new person or scene: kling-v3-omni + reference_video_id (180/240, silent) + 3 reference_image_ids (6 with no clip).
Same at 120/160 when 10s, 1080p, silent do: kling-video-o1 + the clip.
Copy a dance onto the still's person: kling-motion-control. 180/240 per second of the clip (3-30s), silent.
Edit a clip by describing it: gemini-omni-1.1-flash. 140 at 720p (1080p 290, 4K 430, upscales); 3-10s set by the model; 3 reference_image_ids.
Long takes, dialogue, many refs: dreamina-seedance-2-5-260628. 150/330/820 (lite/std/pro), 4-30s, sound. No generation_id: follows reference_image_ids / reference_video_ids (billed as input) or text alone, in aspect_ratio. clip_task + reference_video_id edits/extends it. draft:true = 480p; finalize_draft_id renders it 1080p. whoami: default + models off. @slug or entity_ids attach entities.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Default std 720p; pro 1080p; lite 480p; 4k per guide. | |
| name | No | Library title. | |
| audio | No | Kling 3.0/Omni only, never with a reference clip. | |
| draft | No | ||
| model | No | Default: whoami's. | |
| prompt | No | The motion; for an edit, the change. | |
| dry_run | No | Quote only (exact credits), free. | |
| duration | No | Whole seconds within the model's range. Default 5 (Veo 8); Motion Control uses the clip's. | |
| clip_task | No | ||
| entity_ids | No | ||
| keep_sound | No | Edit: false = new sound | |
| project_id | Yes | ||
| aspect_ratio | No | ||
| end_frame_id | No | Image the clip lands on. | |
| generation_id | No | First-frame image id (Seedance: optional). | |
| extend_direction | No | ||
| finalize_draft_id | No | Draft video id; alone. | |
| reference_video_id | No | Finished video id: acting to keep, movement to copy, or clip to edit. | |
| reference_image_ids | No | Stills to stay faithful to; per-model counts above. | |
| reference_video_ids | No | Seedance: clips to follow, max 30s. | |
| character_orientation | No | Motion Control: whose face, the still's or the clip's. Default video. |
Fetches metadata for a single asset by id.
| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the read-only nature is already known. The description adds 'Fetches metadata' which is consistent but does not disclose additional behavioral traits such as error handling, pagination, or what happens when the asset_id is invalid. With annotations covering the safety profile, the description meets a baseline but offers no extra insight.
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 is a single, concise sentence with no wasted words. It front-loads the action and resource, making it immediately readable. It is an example of efficient specification.
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 one parameter, the description is still incomplete. It fails to indicate what 'metadata' includes or the structure of the response, which is critical for an agent deciding whether to call this tool. Given the many sibling get_* tools, more detail about the returned fields would be necessary for confident selection.
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 schema provides only the parameter name and type (string) with 0% description coverage. The description merely says 'by id', which adds minimal meaning beyond the schema. It does not specify the expected format (e.g., UUID, integer) or any constraints, leaving the agent to guess. The description should compensate for the missing schema descriptions but 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?
The description uses a specific verb ('Fetches') and a clear resource ('metadata for a single asset') qualified by 'by id', which distinguishes it from siblings like list_assets (plural) and get_project/get_task (different resources). An agent can immediately understand its purpose and differentiate it from similar 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 provides no guidance on when to use this tool versus alternatives. It does not mention that list_assets should be used for multiple assets, nor does it clarify when get_meta or get_project might be more appropriate. The agent is left to infer usage 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.
Fresh signed URLs for an existing cutout by generation_id. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description aligns with that (no contradiction). The description adds 'generation_id' as the required identifier and notes it's 'Free', which is useful context beyond the schema. However, it does not explain what a 'cutout' is, whether URLs expire, or any rate limits. For a read-only tool, this 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?
The description is concise and front-loaded with the key information: 'Fresh signed URLs for an existing cutout by generation_id. Free.' Two short sentences, no filler. It efficiently communicates the tool's function and 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?
Given the simple schema (one required parameter) and readOnlyHint annotation, the description is fairly complete. It tells the agent what it returns (fresh signed URLs) and how to identify the cutout (generation_id). It lacks details like URL expiration or how to obtain a generation_id, but for a straightforward read operation, this is sufficient. The presence of annotations and simple schema lowers the bar.
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 schema has one parameter, generation_id, with no description. Schema description coverage is 0%, so the description must compensate. The description does mention that the cutout is identified by generation_id, adding some context about the parameter's purpose. However, it does not explain the format (e.g., UUID, string) or any constraints. Baseline is 3 due to zero coverage, and the description just meets that.
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 'Fresh signed URLs for an existing cutout by generation_id' clearly indicates the tool returns signed URLs for a specific cutout, using a verb (get) and a resource (cutout files). However, the term 'cutout' may not be familiar; it is likely a generated image asset. It distinguishes from siblings like get_asset or get_video by the specific 'cutout' and 'generation_id' concept.
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 when you need fresh signed URLs for a cutout, but it does not explicitly state when to use this tool instead of alternatives like get_asset or get_detections. It does not mention prerequisites (e.g., generation_id from a prior generation) or conditions where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the detection engine sees in an image: item names, categories, textures, colors, and bounding boxes (0-1000 normalized), plus a scene narrative. Free. Use it to 'see' an image's contents, or to pick item names for restyle. Each item has an id (fixed per scan_id) and a label telling repeats apart ("person (left)"); restyle remove takes items [{id}] to remove just that one. 404 = never scanned; run scan_image first.
| Name | Required | Description | Default |
|---|---|---|---|
| target_id | Yes | Generation or asset id. | |
| target_type | No | Default generation. |
Live credit cost of every operation: image tiers per model (generate_*, generate_pro_*, generate_gpt_*), restyle, cutouts, scans, and the per-second video rows (video_sec[ref][audio]; Veo is fixed video_veo_lites). Free. For a whole clip's price use generate_video with dry_run — it multiplies for you.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description needn't restate that. It goes beyond by specifying the pricing model details (per-second video rows, fixed Veo naming) and that it's free, which adds behavioral context that the annotations don't cover. It doesn't disclose return format, but for a zero-param read-only price lookup, the safety and cost implications are well handled.
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, information-packed description with no filler. It front-loads the core purpose, then lists covered items, then adds the free and alternative-usage notes. Every sentence earns its place, and the structure is easy to scan.
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-param read-only price lookups tool, the description covers all an agent needs: what operations are priced, the naming conventions for video rows, the cost (free), and the alternative for clip-level pricing. No output schema or params to compensate for, so completeness is high.
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 has zero parameters, and schema coverage is 100% (nothing to cover). The description's detailed enumeration of the pricing dimensions (model tiers, video row patterns) substitutes for parameter documentation by telling the agent what to look for in the output. This is high value given there's no schema to lean on.
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 ('pricing'), and enumerates exactly what it covers: image tiers per model, restyle, cutouts, scans, and video rows. It clearly distinguishes itself from sibling tools like get_credits (a different concept) by specifying it's the live credit cost of every operation.
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?
Explicitly says it's free, and provides a conditional alternative: for a whole clip's price, use generate_video with dry_run. This gives clear when-to-use and when-not-to-use guidance, and names the alternative tool, which is exactly what an agent needs to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE. For a sheet you own (its generation id): every frame's pixel rect, the per-frame registration, fps, pivot and one animation tag per sequence, as Aseprite JSON that Phaser, Pixi, Godot and Unity import. Ask this instead of measuring gutters in the pixels.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description adds context: it's FREE, returns Aseprite JSON with specific fields, and is for sheets you own. This complements the read-only nature without contradiction, but doesn't detail any potential limitations or side effects (which are minimal for a getter).
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 no redundant words. The purpose is front-loaded ('FREE' and the data returned), and the 'instead of' clause adds value without bloat.
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 adequately covers the return format (Aseprite JSON) and its contents. It doesn't mention error scenarios or pagination, but for a single-parameter getter this is sufficient.
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 description's clarification that generation_id is 'for a sheet you own' is essential. It gives meaning to the only parameter, though it doesn't elaborate on format or validation rules.
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 clearly states the tool returns specific data (frame rects, registration, fps, pivot, animation tag) in a specific format (Aseprite JSON) for a sheet the user owns. It distinguishes itself from sibling tools like plan_sheet or get_asset by its specialized purpose.
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 provides a clear condition ('For a sheet you own (its generation id)') and a hint to use it instead of measuring gutters. However, it doesn't explicitly name alternative tools or state when not to use it, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a task by id; poll long jobs every ~15-30s. A video task (from generate_video) also returns its signed video_url + preview_url once completed. Kling 3.0 takes about 2 minutes, Seedance 2-4; Omni, Motion Control, Veo and Gemini Omni 3-6. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Lists the user's assets (uploads + references); project_id narrows to one project. Each has permanent_url, a link that never expires.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| category | No | ||
| project_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds one genuinely useful trait beyond structured data — that each asset carries a permanent_url that never expires — but says nothing about pagination, result size, ordering, or whether category filters behave as expected for a listing call.
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 clauses with no filler; the listing scope is front-loaded and the project_id caveat follows immediately. Nothing could be cut without losing 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 zero-required-parameter list tool with annotations covering safety and no output schema, the description is minimally viable and even discloses one return field (permanent_url). It falls short on how limit/offset/category work, which an agent needs to page or filter 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 0% and three of four parameters (limit, offset, category) are undocumented anywhere. The description explains only project_id's narrowing behavior, so it partially compensates but leaves the pagination and filtering parameters completely opaque.
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 the user's assets') and clarifies scope by defining assets as uploads plus references, which is a meaningful distinction. It does not contrast itself against siblings like get_asset or list_generations, but the core 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?
The only usage signal is 'project_id narrows to one project', which is really parameter semantics rather than when-to-use guidance. There is no statement of when to prefer this over get_asset, list_generations, or search, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Characters, props, places; ref ids are generate_video reference_image_ids. -@slug in a prompt leaves one out; @slug/alone drops its items. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | One entity in full: refs, sheet (prefer sheet.asset_id as a ref), looks, links, facets, bio, voice, specs (a prop's or place's facts by stable key, e.g. top_speed). | |
| kind | No | skin = an outfit with its accessories, reusable on anybody. |
Lists generations in a project, newest first; favorites:true = only the hearted (liked) ones, each with an image_url to view.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| favorites | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond annotations: it specifies newest-first ordering, defines favorites:true as 'only the hearted (liked) ones', and promises each result includes an image_url. This gives the agent concrete expectations for output content without contradicting 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?
Two compact clauses deliver the core purpose, ordering, filter, and return format with no repetition or filler. The action and resource are front-loaded, and the filter syntax is explained inline, making the description lean and immediately scannable.
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?
The description covers the main return (image_url) and ordering, which partially compensates for the missing output schema. However, it does not mention pagination semantics (limit/offset), default behavior, error conditions (e.g., unknown project_id), or anything beyond the basic list scenario. For a tool with 4 parameters and no output schema, this is adequate but leaves 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 0%, so the description carries the full burden. It adds meaning only for 'favorites' ('only the hearted (liked) ones'). It does not explain limit, offset, or project_id beyond their bare names, nor how they interact. Given four parameters, this is insufficient compensation for the missing 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?
The description clearly states the action ('Lists'), the resource ('generations in a project'), and adds ordering ('newest first') which distinguishes it from other list tools like list_assets or list_tasks. The combination of verb, resource, and specific behavior leaves no ambiguity about the tool's purpose.
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 naming the resource and scope ('generations in a project'), and explains the favorites filter. However, it does not explicitly contrast with sibling tools (e.g., when to use list_assets instead) or state any exclusion conditions, so an agent must infer the appropriate selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the user's projects, most-recently-updated first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates that this is a safe read operation. The description adds the ordering behavior, but does not disclose pagination behavior, return format, or any other operational details. With annotations present, this 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?
A single, front-loaded sentence with no filler. Every word adds meaning, and the most important scoping information ('the user's projects') comes first.
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?
The description is sufficient for a simple read-only list operation, but it leaves the pagination parameters undocumented and provides no output expectations. Given the low schema description coverage and missing output schema, more detail would help.
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 description must compensate for the undocumented limit and offset parameters. It does not mention pagination at all, though the parameter names are conventional enough that an agent may infer their 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?
States a specific verb ('Lists'), a clear resource ('the user's projects'), and a sorting behavior ('most-recently-updated first'). This clearly distinguishes it from sibling tools like list_assets or list_generations.
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 is given on when to use this tool versus get_project, resolve_project, or other list tools. The intended context is implied by the name and description, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists background tasks (generations, uploads, scans, exports).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this as a safe read operation. The description adds useful context about which task types are included, but it does not disclose behaviors like status filtering, pagination, ordering, or whether all users' tasks are returned. With annotations covering safety, a mid score 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?
The description is concise and front-loaded with the verb and resource, and the examples are informative without being verbose. It earns its place by clarifying what counts as a background task. No redundant 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?
With no output schema and two undocumented parameters, the description does not explain what the returned task objects look like, how status filtering works, or how limit behaves. It is adequate for a trivial read-only list, but the missing parameter and return-value context leaves gaps 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 0% and the description is silent about the 'limit' and 'status' parameters. Since there is no parameter documentation in the schema either, the agent receives no explanation of acceptable status values or how limit affects results. The description adds no meaning beyond the parameter names themselves.
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 clearly states the verb 'Lists' and the resource 'background tasks', and gives concrete examples (generations, uploads, scans, exports). It is distinct enough from siblings like get_task or cancel_task, though it does not explicitly contrast with list_generations or list_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?
The description provides no guidance on when to use this tool versus alternatives such as list_generations or list_assets. It simply states what it lists, leaving the agent to infer usage context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds a project by exact name (case-insensitive) or creates it if none matches; or, with project_id, returns that project. Idempotent and free. Use this to follow the one-project-per-folder convention: resolve the folder's name, then pass the returned project_id to other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Project name, 1-100 chars. | |
| project_id | No | Instead of name: fetch this project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds useful behavior: it is free, matches names case-insensitively, and can create a project if no match exists. No contradictions with 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 short sentences with no waste. The core behavior is front-loaded, followed by idempotency/free status and a concrete usage pattern. Every sentence contributes.
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 two-parameter tool with no output schema, the description covers lookup, creation, parameter alternatives, and intended workflow. It does not describe the return shape in detail, but that 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 coverage is 100%, so both name and project_id are documented. The description adds relational meaning: they are alternatives ('Instead of name'), and name matching is exact but case-insensitive.
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 precise behavior: find by exact name (case-insensitive), create if absent, or fetch by project_id. This clearly separates it from siblings like list_projects by specifying unique matching/creation semantics.
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 an explicit usage convention: follow the one-project-per-folder workflow by resolving the folder name and passing the returned project_id onward. It does not explicitly name alternative tools or state when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edits an existing image with AI. COSTS CREDITS (generate_* pricing, like generate_image). Always creates a NEW generation; the original is untouched. Modes: plain-text edit (just instructions); one-click product placement (action bring + reference_id — places the reference's product into the scene at true scale, relit); recolor/remove/add items (use get_detections for item names); merge two images (merge_bias 0=reference dominates, 100=base dominates); art-style transfer (action style + style_intensity 0-100). reference_id can be an asset OR a generation you own. @slug in the prompt or entity_ids attach a saved entity's sheet (list_entities).
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | Items by name (every instance) or, remove only, by get_detections id (that one instance). Required for remove. | |
| action | No | Default bring. | |
| scan_id | No | The scan_id item ids came from. Default newest. | |
| asset_id | No | An uploaded asset as the base instead; never both. | |
| entity_ids | No | ||
| merge_bias | No | merge only: 0 reference dominates - 100 base dominates. Default 50. | |
| project_id | Yes | Project for the result. | |
| resolution | No | ||
| blend_level | No | add only: 0 raw composite - 100 fully unified. Default 50. | |
| merge_scope | No | merge only. Default scene. | |
| aspect_ratio | No | ||
| instructions | No | Free-text edit instructions. | |
| reference_id | No | Asset or generation to take the product/colors/style/content from. | |
| generation_id | No | The base photo to edit (or asset_id). | |
| style_intensity | No | style only: 0 subtle tint - 100 full reimagine. Default 75. |
Retries a failed task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations reveal the operation is mutating and non-destructive, but the description adds no context beyond that, such as whether retrying reuses original inputs, re-queues the task, or may consume credits. The description does not contradict the annotations, but it also provides no behavioral detail.
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 single sentence is concise and front-loaded, but it is also underspecified: it essentially restates the title and leaves meaningful behavioral and parameter guidance out. This is brevity rather than efficient completeness.
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 task-lifecycle mutation with no output schema, the description does not state what a successful retry returns, what state transitions occur, or whether retry is only valid after failure. It is too thin to fully support 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?
With 0% schema description coverage, the description needed to explain task_id, but it only implies that the ID identifies the failed task. There is no explicit statement that task_id is the failed task's identifier or any detail about where to obtain it.
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 action, 'retries', and a specific resource, 'a failed task'. It is clear enough to distinguish from read-only task operations like get_task/list_tasks and from cancel_task, though it does not explicitly name a sibling.
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 retry versus cancel or inspect a task, no mention of prerequisites such as the task needing to be in a failed state, and no discussion of alternatives. The phrase 'failed task' implies a condition but nothing explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs the detection scan on a generation or asset (items, colors, textures, scene). Costs credits (see get_pricing); takes ~5-20s and returns when done. Results power search and get_detections. Usually unnecessary — every generation and import is scanned automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| target_id | Yes | Generation or asset id. | |
| target_type | No | Default generation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals that the tool costs credits, takes 5-20 seconds, and returns synchronously when done. It also discloses that results are consumed by search and get_detections, giving the agent a clear picture of side effects and resource implications.
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 is two compact sentences with zero filler. The core purpose is front-loaded, followed by cost, latency, and a strong 'usually unnecessary' caveat. Every clause adds actionable 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 tool with only two parameters and no output schema, the description covers the essentials: what it does, cost, latency, and when to avoid it. It does not specify what the return value looks like (e.g., a task ID), but given the presence of sibling tools like get_task, this omission is 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 coverage is 100%, with target_id and target_type already described. The description merely restates 'generation or asset' without adding new format or usage details, so it does not elevate the parameter understanding beyond what the schema already provides.
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 clearly states the tool 'runs the detection scan' on a generation or asset, and enumerates the detection types (items, colors, textures, scene). It distinguishes itself from retrieval tools like get_detections by focusing on the action of scanning rather than reading results.
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 explicitly says 'Usually unnecessary' because scans happen automatically, which tells the agent not to use it by default. It also notes that results power search and get_detections, implying those are the downstream consumers, though it stops short of naming when exactly to force a scan (e.g., after a failed scan).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detection-aware search across the user's assets and generations — matches what the scanner SAW inside each image (item names, colors, textures, scene), not just titles or prompts. Modes: text (default; requires query), color (ranks by closeness to a hex color), similar (ranks by likeness to an anchor image), browse (no query; newest first — use it to explore the library). Scope with project_id; set include_regions to get each hit's detected items with bounding boxes. Text results can include the matched instant INSIDE an indexed video: such hits carry is_video plus a video_moment object (time_ms = the exact millisecond). Filter to one category with gen_type (e.g. gen_type:"video" for clips only). Each hit's image_url is a 600px preview: re-read the original from list_generations before placing a hit in a document.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Default text. | |
| type | No | Limit to generated images or uploads. | |
| color | No | mode=color: 6-digit hex like #7a1f2b. | |
| limit | No | 1-100, default 40. | |
| query | No | Plain-language search terms. Required for mode text; optional re-ranker input for mode color. | |
| style | No | ||
| aspect | No | Comma list: portrait, landscape, square, or exact ratios like 16:9. | |
| colors | No | Only images containing these colors (comma list of names or hex values). | |
| offset | No | ||
| gen_type | No | Limit to one kind of generation. | |
| project_id | No | Limit to one or more projects (comma-separated ids). | |
| similar_to | No | mode=similar: the anchor generation or asset id. | |
| similar_mode | No | mode=similar: likeness lens. Default all. | |
| similar_type | No | mode=similar: what similar_to refers to. | |
| include_regions | No | Add each hit's detected items with bounding boxes (0-1000 normalized). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers safety, and the description adds substantial behavioral context beyond that: results can include matches inside videos with an exact video_moment timestamp, and each image_url is only a 600px preview rather than the full original. This materially changes how an agent should use the returned 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?
The description is dense but well structured: core capability first, then mode definitions, then scoping/filtering, then special result behaviors, then a caveat with an alternative tool. Every sentence adds operational value, and the length is justified by the tool's 15 parameters and lack of an output 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 complex search tool with no output schema, the description covers the critical gaps: mode interactions, required versus optional inputs, result shapes like video_moment and regions, preview limitations, and the pointer to list_generations for full-fidelity originals. Remaining details like limit and offset are already present 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 high at 87%, so the description does not need to re-document parameters. It adds value by explaining mode-dependent semantics such as query being required for text mode, similar modes requiring anchors, and include_regions producing bounding-box data, plus the video_moment consequence of certain text results.
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: detection-aware search across the user's assets and generations. It distinguishes itself from title/prompt-based retrieval and from sibling listing tools by emphasizing what the scanner SAW inside each image, and it breaks out four distinct modes so an agent immediately understands the tool's scope.
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 mode-specific usage rules: text requires a query, color ranks by hex closeness, similar needs an anchor, and browse requires no query and is for exploration. It also instructs when to step outside this tool, telling the agent to re-read the original from list_generations before using a hit in a document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE. The menus a sheet is made from, so nothing is invented: kinds, keyable grounds, art styles (photographic, drawn, painted), animation sequences by subject (kind frames) or by game type (kind sprites) with frame counts per detail level, the levels, and the image models with their resolution ceilings. No arguments = the index, ids and one-liners. family + type = that type's sequences with their full frame lists. The ids go straight into generate_sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | A type id within that family. | |
| family | No | A sequence family id from the index, with type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already flagging a safe read operation, the description adds useful behavioral context: 'FREE' signals cost behavior, and it discloses mode-dependent response content (index vs full frame lists). It does not mention rate limits or auth, but for a read-only menu tool with this annotation, the additional context is sufficient.
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 is dense but economical; every sentence adds either domain context or call behavior. The leading 'FREE' and core purpose are front-loaded, and the rest of the content explains invocation modes without filler. The first sentence is a long enumeration, but it remains readable and purposeful.
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 no output schema, the description carries the burden of explaining return values, and it does: no arguments yields the index, while family+type yields full frame lists. It also mentions frame counts per detail level and resolution ceilings, which are the key data points an agent would need. It is complete enough for a read-only menu 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?
The schema already documents both parameters, so the baseline is 3. The description goes beyond by explaining the no-argument case, the family+type combination, and the relationship to generate_sheet. This adds practical meaning to the parameters rather than just repeating schema names.
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 clearly identifies the resource as the menus/options a sheet is made from: kinds, keyable grounds, art styles, animation sequences, levels, and image models. It also differentiates from generate_sheet by stating 'The ids go straight into generate_sheet.' It lacks an explicit verb like 'returns' or 'lists,' but the behavioral intent is unambiguous from 'No arguments = the index, ids and one-liners.'
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 specifies two calling modes: no arguments returns the index, and family + type returns that type's sequences with full frame lists. This tells the agent exactly when to call with parameters versus empty. It names generate_sheet as the downstream consumer but does not explicitly discuss when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-renders an existing generation at a higher resolution (sharper detail). COSTS CREDITS (generate_* at the TARGET resolution). Creates a NEW generation in the source's own project. An uploaded asset works as the base too (asset_id, not both); its result goes to project_id or the asset's project.
| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | No | ||
| project_id | No | asset_id only. | |
| resolution | Yes | Target resolution; drives cost. | |
| generation_id | No |
Who you are, your plan, credits (balance and any daily cap), storage used and quota, and the server's version and capabilities. Free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the main safety trait, and the description adds useful context by noting the call is free and listing response contents such as server version and capabilities. However, it does not disclose potential authentication requirements, error conditions, or rate limits, which would be valuable given there is no output schema. The description adds some context but not rich behavioral detail beyond the 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?
The description is a single, information-dense sentence that front-loads the primary purpose and appends the cost note at the end. Every word contributes meaning, with no repetition of schema content or filler. This is exemplary conciseness for a simple 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 parameterless, read-only account-query tool, the description gives a complete high-level inventory of the response: identity, plan, credits including daily cap, storage usage/quota, and server version/capabilities. It does not specify data types or units, but the lack of an output schema makes some ambiguity unavoidable. Overall, an agent knows exactly what information it can obtain from 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?
The tool accepts zero parameters and the input schema is an empty object, so there is nothing for the description to explain. Per the zero-parameter baseline, the description needs no additional parameter documentation. There is no gap in this dimension.
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 clearly identifies the tool as an account/status query, enumerating exactly what it returns: identity, plan, credits (balance and daily cap), storage used/quota, and server version/capabilities. It is instantly distinguishable from all sibling tools, none of which provide this account-level information. Despite not using an explicit verb, 'whoami' is a standard convention and the description 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?
The description provides clear context: use this tool when you need the current user's identity, plan, credits, storage, or server capabilities. No sibling tool overlaps with this functionality, so there are no alternatives to exclude. The absence of an explicit 'when to use' statement is acceptable because the tool's purpose is self-evident and uniquely scoped.
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.
restyle4 fields changedInput schema / properties / items / descriptionPrevious value: -"Item names to target (from get_detections). Required for remove."New value: +"Items by name (every instance) or, remove only, by get_detections id (that one instance). Required for remove."Input schema / properties / items / items / properties / idAdded value: +{
+ "type": "integer"
+}Input schema / properties / items / items / requiredRemoved value: -[
- "name"
-]Input schema / properties / scan_idAdded value: +{
+ "description": "The scan_id item ids came from. Default newest.",
+ "type": "string"
+}expand_image3 fields changedInput schema / properties / asset_idAdded value: +{
+ "type": "string"
+}Input schema / properties / project_idAdded value: +{
+ "description": "asset_id only.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "generation_id",
- "target_aspect_ratio"
-]New value: +[
+ "target_aspect_ratio"
+]restyle3 fields changedInput schema / properties / asset_idAdded value: +{
+ "description": "An uploaded asset as the base instead; never both.",
+ "type": "string"
+}Input schema / properties / generation_id / descriptionPrevious value: -"The base photo to edit."New value: +"The base photo to edit (or asset_id)."Input schema / requiredPrevious value: -[
- "generation_id",
- "project_id"
-]New value: +[
+ "project_id"
+]upscale_image3 fields changedInput schema / properties / asset_idAdded value: +{
+ "type": "string"
+}Input schema / properties / project_idAdded value: +{
+ "description": "asset_id only.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "generation_id",
- "resolution"
-]New value: +[
+ "resolution"
+]generate_video16 fields changedInput schema / properties / aspect_ratioAdded value: +{
+ "enum": [
+ "16:9",
+ "9:16",
+ "1:1",
+ "4:3",
+ "3:4",
+ "21:9"
+ ],
+ "type": "string"
+}Input schema / properties / clip_taskAdded value: +{
+ "enum": [
+ "edit",
+ "extend"
+ ],
+ "type": "string"
+}Input schema / properties / draftAdded value: +{
+ "type": "boolean"
+}Input schema / properties / dry_run / descriptionPrevious value: -"Quote only: exact credits_cost, nothing submitted or charged."New value: +"Quote only (exact credits), free."Input schema / properties / end_frame_id / descriptionPrevious value: -"Image the clip lands on (Kling 3.0, Veo, Gemini Omni, Seedance)."New value: +"Image the clip lands on."Input schema / properties / extend_directionAdded value: +{
+ "enum": [
+ "forward",
+ "backward"
+ ],
+ "type": "string"
+}Input schema / properties / finalize_draft_idAdded value: +{
+ "description": "Draft video id; alone.",
+ "type": "string"
+}Input schema / properties / generation_id / descriptionPrevious value: -"Source image id (generation or upload)."New value: +"First-frame image id (Seedance: optional)."Input schema / properties / keep_soundAdded value: +{
+ "description": "Edit: false = new sound",
+ "type": "boolean"
+}Input schema / properties / mode / descriptionPrevious value: -"Default std (720p-class); pro 1080p-class; 4k where the guide lists it."New value: +"Default std 720p; pro 1080p; lite 480p; 4k per guide."Input schema / properties / mode / enumPrevious value: -[
- "std",
- "pro",
- "4k"
-]New value: +[
+ "lite",
+ "std",
+ "pro",
+ "4k"
+]Input schema / properties / nameAdded value: +{
+ "description": "Library title.",
+ "type": "string"
+}Input schema / properties / prompt / descriptionPrevious value: -"The motion to depict; for a Gemini Omni edit, the change to make."New value: +"The motion; for an edit, the change."Input schema / properties / reference_video_id / descriptionPrevious value: -"A finished video id: the acting to keep (Omni/O1), the movement to copy (Motion Control), the clip to edit (Gemini Omni)."New value: +"Finished video id: acting to keep, movement to copy, or clip to edit."Input schema / properties / reference_video_idsAdded value: +{
+ "description": "Seedance: clips to follow, max 30s.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / requiredPrevious value: -[
- "generation_id",
- "project_id",
- "prompt"
-]New value: +[
+ "project_id"
+]add_video1 field changedInput schema / properties / keep_originalAdded value: +{
+ "type": "boolean"
+}generate_video1 field changedInput schema / properties / model / descriptionPrevious value: -"Default kling-v3."New value: +"Default: whoami's."list_entities1 field changedInput schema / properties / id / descriptionPrevious value: -"One entity in full: refs, sheet (prefer sheet.asset_id as a ref), looks, links, facets, bio, voice."New value: +"One entity in full: refs, sheet (prefer sheet.asset_id as a ref), looks, links, facets, bio, voice, specs (a prop's or place's facts by stable key, e.g. top_speed)."add_video1 field changedInput schema / properties / metadataAdded value: +{
+ "type": "object"
+}add_videogenerate_video2 fields changedInput schema / properties / end_frame_id / descriptionPrevious value: -"Image the clip lands on (Kling 3.0, Veo, Gemini Omni)."New value: +"Image the clip lands on (Kling 3.0, Veo, Gemini Omni, Seedance)."Input schema / properties / model / enumPrevious value: -[
- "kling-v3",
- "kling-v3-omni",
- "kling-video-o1",
- "kling-motion-control",
- "veo-3.1-lite-generate-preview",
- "gemini-omni-1.1-flash"
-]New value: +[
+ "kling-v3",
+ "kling-v3-omni",
+ "kling-video-o1",
+ "kling-motion-control",
+ "veo-3.1-lite-generate-preview",
+ "gemini-omni-1.1-flash",
+ "dreamina-seedance-2-5-260628"
+]generate_image2 fields changedInput schema / properties / model / descriptionPrevious value: -"gemini-3.1-flash-image = Nano Banana 2 (default), gemini-3-pro-image = Nano Banana Pro, gpt-image-2.5-flare = GPT 2.5 Flare, gpt-image-2.5-sunburst = GPT 2.5 Sunburst."New value: +"gemini-nano-banana-2.1 = Nano Banana 2.1 (default), gemini-3-pro-image = Nano Banana Pro, gpt-image-2.5-flare = GPT 2.5 Flare, gpt-image-2.5-sunburst = GPT 2.5 Sunburst."Input schema / properties / model / enumPrevious value: -[
- "gemini-3.1-flash-image",
- "gemini-3-pro-image",
- "gpt-image-2.5-flare",
- "gpt-image-2.5-sunburst"
-]New value: +[
+ "gemini-nano-banana-2.1",
+ "gemini-3-pro-image",
+ "gpt-image-2.5-flare",
+ "gpt-image-2.5-sunburst"
+]generate_sheet2 fields changedInput schema / properties / model / descriptionPrevious value: -"Default gemini-3.1-flash-image (Nano Banana 2). GPT stops at 2K."New value: +"Default gemini-nano-banana-2.1 (Nano Banana 2.1). GPT stops at 2K."Input schema / properties / model / enumPrevious value: -[
- "gemini-3.1-flash-image",
- "gemini-3-pro-image",
- "gpt-image-2.5-flare",
- "gpt-image-2.5-sunburst"
-]New value: +[
+ "gemini-nano-banana-2.1",
+ "gemini-3-pro-image",
+ "gpt-image-2.5-flare",
+ "gpt-image-2.5-sunburst"
+]delete_asset1 field changedInput schema / properties / forceAdded value: +{
+ "type": "boolean"
+}add_image1 field changedInput schema / properties / metadataAdded value: +{
+ "type": "object"
+}list_assets1 field changedInput schema / properties / project_idAdded value: +{
+ "type": "string"
+}add_imagecreate_projectgenerate_sheet2 fields changedInput schema / properties / prompt_onlyAdded value: +{
+ "description": "Free: just the plan and prompt, for generate_image as given.",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "project_id",
- "kind"
-]New value: +[
+ "kind"
+]get_creditsget_entityget_metaget_projectget_storageget_videoimport_imagelist_entities1 field changedInput schema / properties / idAdded value: +{
+ "description": "One entity in full: refs, sheet (prefer sheet.asset_id as a ref), looks, links, facets, bio, voice.",
+ "type": "string"
+}list_favoriteslist_generations1 field changedInput schema / properties / favoritesAdded value: +{
+ "type": "boolean"
+}plan_sheetresolve_project2 fields changedInput schema / properties / project_idAdded value: +{
+ "description": "Instead of name: fetch this project.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "name"
-]upload_assetlist_entities2 fields changedInput schema / properties / kind / descriptionAdded value: +"skin = an outfit with its accessories, reusable on anybody."Input schema / properties / kind / enumPrevious value: -[
- "character",
- "prop",
- "location",
- "look"
-]New value: +[
+ "character",
+ "prop",
+ "location",
+ "look",
+ "skin"
+]generate_image1 field changedInput schema / properties / entity_idsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}generate_sheet1 field changedInput schema / properties / entity_idsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}generate_video2 fields changedInput schema / properties / entity_idsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / reference_image_ids / descriptionPrevious value: -"Stills to stay faithful to. Omni/O1 up to 6, or 3 beside a reference clip (Kling counts both against one list). Gemini Omni 3."New value: +"Stills to stay faithful to; per-model counts above."plan_sheet1 field changedInput schema / properties / entity_idsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}restyle1 field changedInput schema / properties / entity_idsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}list_entities1 field changedInput schema / properties / kind / enumPrevious value: -[
- "character",
- "prop",
- "location"
-]New value: +[
+ "character",
+ "prop",
+ "location",
+ "look"
+]get_entitylist_entitiescancel_taskcreate_projectcutoutdelete_assetexpand_imagegenerate_imagegenerate_sheetgenerate_videoget_assetget_creditsget_cutoutget_detectionsget_metaget_pricingget_projectget_sheet_atlasget_storageget_taskget_videoimport_imagelist_assetslist_favoriteslist_generationslist_projectslist_tasksplan_sheetresolve_projectrestyleretry_taskscan_imagesearchsheet_optionsupload_assetupscale_imagewhoamiPersonal memory layer: files, notes, messages, tasks and email, semantically indexed.
Digital asset manager - upload, organize, search, and generate on-brand images and videos
One semantic search across your sites, Drive, Notion, email, files and Basecamp.
AI-native digital asset management: semantic search, generative image edits, and CDN delivery.
Add one secure layer between your agents and this server.
