Showoff.dev – AI Mockup Generator

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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds real behavior beyond that: the render happens in the user's browser, the call returns a render page plus what is still missing, screenshots can be passed as URLs or via returned curl commands for disk files, and omitting `blocks` falls back to a standard film. It does not discuss authentication or limits, but for a creative-generation tool the disclosure is well above the annotation floor.

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 correctly: purpose, formats, then routing to siblings, then composition rules, then return value. It is dense and long, and a few clauses (e.g. the drop/beat rules) duplicate things the schema also explains, but nearly every sentence carries actionable instruction rather than 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 20-parameter, deeply nested creative tool with no output schema, the description covers the workflow (story first, blocks in order), the fallback path, the return value, and where to read more. What it delegates to the guide and to the 100%-covered schema is reasonable, though the guide reference means the description alone is not fully self-contained.

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 genuine cross-parameter semantics the schema cannot: `story` is written before `blocks`, `blocks` elements must narrate the story in order, lines are 2-4 words per language, the end card is brand name slamming into `merge_into`, and `on_drop` belongs to exactly one block. That is more than the schema conveys field-by-field.

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?

Opens with a specific verb and resource ('Creates a cinematic, music-synced launch video for an app or web product') and immediately enumerates the three concrete output shapes (9:16 Reel, 16:9 film, short teaser). It explicitly names the sibling tools it is not (create_project, update_launch_video), so an agent can route without opening another 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?

States when to use it ('whenever the user wants a launch video, Reel or teaser') and when not to, with named alternatives: create_project for stills/App Store sets/animated film, update_launch_video for edits. It also prescribes the ordering of work ('Write the story first, then compose blocks in order') and points at the guide section to read first.

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

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

Annotations only declare readOnly=false, destructive=false and openWorld=true, so the description carries most of the behavioral burden and does well: it discloses the pre-save review ('if it has errors, nothing is created and you get the findings with fixes'), the disk-file/curl workflow, and the return payload. It stops short of stating auth/permission requirements or rate/limit behavior, leaving a small 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-loads the one-call creation scope, then routing, then the review behavior, then the disk-file caveat and the return shape. Dense but every clause is functional; the long compound first sentence is the only minor cost to scanability.

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 creation scope, sibling routing, the destructive-failure review behavior, the disk-file path and the return fields, which is strong for a 12-parameter, mutation, no-output-schema tool. Missing only permission/auth notes and pagination-like limits, which are minor for this 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 coverage is 100%, so the baseline is 3. The description nonetheless adds cross-parameter semantics beyond the schema: how reference overrides composition/format, that device default is iPhone unless asked otherwise, and the template_id interaction with devices and screenshot device_index.

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 precise verb+resource ('Creates a new still-image or film mockup project in one call') and enumerates the constituent parts it composes (devices, composition, screenshots, palette, texts, ops). It explicitly distinguishes itself from siblings by naming create_launch_video, duplicate_project and edit_scene with the conditions that select 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?

Explicit routing: 'use create_launch_video for a music-synced launch video, duplicate_project for a variant of an existing project, and edit_scene to change a project that already exists.' It also gives a within-tool branch (files on disk → create first, then run curl commands), covering both when-to-use and when-not.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them: the history is destroyed and cannot be restored, and it explains the confirm_name guard's failure mode ('otherwise nothing is deleted').

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 clauses with the irreversible scope constraint front-loaded, followed by the when-to-use restriction and the guard parameter. No filler sentences; every clause carries operative 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 destructive, two-parameter tool with an output schema absent and annotations covering the safety hints, nothing an agent needs to invoke it correctly is missing: scope, irreversibility, precondition, and the confirm_name contract are all 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 coverage is 100%, so the baseline is 3. The description goes further by clarifying that confirm_name must be the exact current name sourced from list_projects and that a mismatch silently aborts the deletion, adding meaning not present in the schema's terse property 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 (Deletes) and resource (project) with precise scope: ONE, permanently, including its history. An agent can distinguish this from create_project, duplicate_project, and restore_version 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?

Explicitly limits use to the case where the user asks to delete this very project, and explicitly excludes autonomous cleanup ('never to tidy up on your own') and bulk deletion ('never for several at once'). It also routes the agent to list_projects for obtaining the exact name.

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

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

Annotations already declare a non-read-only, non-destructive write, and the description adds genuinely new behavioral context: the original stays untouched, the copy is placed adjacent in the same folder, it returns the new project_id plus an editor/render link, and that id should be threaded into subsequent calls. That is a full workflow contract beyond what the annotations encode.

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?

Four sentences that are front-loaded with the core action and scope, then usage, then side effects, then return value and next step. Every sentence carries distinct 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?

There is no output schema, and the description compensates by stating exactly what is returned (project_id, editor/render link). Combined with the folder default and the original-untouched guarantee, an agent has everything needed to invoke and chain this 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 name, folder, and project_id are already documented with their defaults and formats. The description reinforces the folder behavior ('next to it in the same folder') and naming intent, but adds little syntax or 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?

States a specific verb (Copies) and resource (a project), enumerates what the resource can be (image, film, launch video), and spells out what is carried over (devices, screenshots, song, blocks) plus where the copy lands (next to it in the same folder). An agent can distinguish this from create_project without opening either schema.

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

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

Explicitly names the intended case (a variant the user wants beside the original, with concrete examples like another song/color/language) and the alternative (create_project or create_launch_video for something new). It even routes the agent to the follow-up tools (edit_scene, update_launch_video) for modifying the copy.

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

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

Annotations declare only the safety profile (readOnly false, destructive false, openWorld false). The description goes well beyond: batch atomicity ('either all apply or none', later ops see earlier ones), the reject-and-return-findings behavior on error, live visibility to other viewers, version creation on every save, and automatic camera re-framing/text re-layout after geometry changes unless keep_camera is true.

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 prose is dense but mostly earns its place; the ops enumeration in the first sentence is somewhat redundant with the schema's full catalog. Front-loading atomicity and sibling routing is good, but the run-on sentences mix several concerns without separation.

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 6-parameter, 60-op mutation tool with no output schema, the description covers atomicity, error handling, preview/version side effects, and prerequisite conventions. It even names what the call returns ('the review and a preview sketch'), which is needed since there is no output 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 100% and the ops catalog is verbose in-schema, yet the description adds routing value: it points to `ops` for the full catalog and explains that keep_camera suppresses the automatic re-frame, and that folder without ops only files the project. It adds semantic framing rather than duplicating parameter definitions.

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 (changes/edits) and resource (a still or film project) and enumerates the op families it covers (add/move/remove devices, screens, texts, background, camera, motion, highlights, store sets, rename). It explicitly distinguishes itself from siblings update_launch_video and create_project, so an agent can route without opening schemas.

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?

Explicit routing: 'Use it for every change to an existing image or film project; use update_launch_video for a launch video and create_project to start a new one.' It also states the dry_run-only review path, so the agent knows when to review vs commit.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral load: render time of 5–30 seconds, a busy renderer that charges nothing and names a retry delay, a 7-day URL expiry, and metered full-quality exports with per-plan allowances. That is exactly the cost/retry context an agent needs before calling.

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 action and result, then handles alternatives and cost. It is long but nearly every sentence carries distinct information; the store-set and width/format asides could arguably be compressed.

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 describes the return (viewable image plus downloadable URL and its 7-day validity), the cost model, the busy path, and the store-set deviation. Nothing material for correct invocation 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 3 is the floor, but the description adds cross-parameter semantics the schema does not: width and format 'do not apply' to store sets, play is an obsolete alias for stores, and the charge only follows rendered previews rather than upfront. Slightly short of 5 because individual formats/bounds 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?

States a specific verb and resource ('renders the finished mockup on the server with the real 3D renderer') plus what comes back (image to look at and a 7-day download URL). It explicitly separates itself from render_preview and set_store_set, so an agent can route without opening either schema.

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

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

Gives explicit when/when-not: 'Use render_preview for quick checks while building, this for the result', names set_store_set as the tool for bulk store exports, and ties full-quality width to a user request. The busy-renderer retry path and accept_charge precondition are spelled out.

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

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

Annotations cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: pass/fail semantics, that empty screens count as errors, that it returns errors with fixes, and what the success return differs by project type. This is well beyond what the structured fields disclose.

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 action, then timing, then outcome routing in short clauses with no filler. Length is justified by the multi-branch next-step guidance, and each sentence carries distinct 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?

With no output schema, the description compensates by describing both failure returns (error list with fixes) and success returns per project type (editor link, render page, export_image follow-up). For a one-parameter read-only check tool, nothing an agent needs 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% for the single project_id parameter, so the schema already documents it fully (including its source: create_project or list_projects). The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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 ('Runs the strict final check') plus its scope ('before you hand the work to the user') and explicitly distinguishes itself from review_scene. An agent can tell it apart from review_scene and render_preview without opening schemas.

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 timing ('once at the end, after review_scene and render_preview look right') and names the alternative for the other phase ('while building use review_scene'). It also routes the agent to the correct follow-up tool per project type (export_image vs editor link vs render page).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and the description's 'Read-only' simply restates that. However it adds real behavioral context beyond annotations: the return payload includes ready-made curl commands (replace_commands) covering filled slots, and running them causes a side-effect (swapping a screenshot) despite this call being read-only. That is a meaningful disclosure. Gaps remain around pagination/limits and whether the curl commands mutate state server-side beyond screenshots.

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 dense paragraph front-loads the returned state and then routes to alternatives, with no filler sentences. It is tightly packed but readable; the run-on construction with multiple semicolons slightly reduces scannability.

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 full burden of describing returns and does so explicitly (render_url, blocks, music, ready, replace_commands), plus what is missing. For a one-parameter read 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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents project_id fully under its own baseline. The 'block indexes and slot names' mentioned in the description refer to outputs, not inputs, so it adds no extra meaning to the parameter itself.

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 (reads the state of a launch video) and enumerates exactly what state is exposed: render page, song with tempo, drops, chosen section, numbered blocks, and what is still missing. It is clearly distinguishable from siblings get_scene and render_preview without opening either schema.

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

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

It states both when to use it ('before update_launch_video to get block indexes and slot names, and to replace screenshots') and which siblings to prefer instead ('render_preview to see frames, get_scene only for still or film projects'). Alternatives and selection conditions are explicit.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, but the description still adds real behavioral context: the exact returned payload fields, the fact that empty screens come with upload commands, and an editor_url/open_in_editor. Repeating 'Read-only' is redundant with annotations, which caps this at 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 core action and the return contents before the routing sentence. Dense but almost every clause earns its place; the enumeration is slightly long, but each field listed is meaningful for downstream edit_scene calls.

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 does so thoroughly (scene, review, editor_url, open_in_editor, upload commands). Combined with explicit sibling routing for a read-only tool, 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?

Single project_id parameter with 100% schema description coverage, so the schema already explains the id and its source. The description adds no extra syntax or format detail for the parameter; 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 ('Reads the current scene of a still or film project') and then enumerates exactly what the scene contains (object ids, positions, angles, screen media, last editor, review). An agent can distinguish it from render_preview, review_scene and get_launch_video 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?

Explicitly names the primary use case ('before edit_scene to get object ids and current values') and the secondary one ('see what a person changed'), then routes to three alternatives with their distinct purposes — render_preview, review_scene, get_launch_video. Nothing 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only; it never creates or changes a project' largely reinforces structured data. However, the description adds genuinely new behavioral context: the return shape (`template`, `scene`, `review`) and that the sketch is omitted when preview is false. This goes beyond what annotations and schema provide.

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 content is front-loaded with the purpose, then ordered as workflow, safety note, and return values. It is dense but every clause adds information; the main cost is a long first sentence that mixes purpose with an enumeration of return contents.

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, but the description names the returned keys (`template`, `scene`, `review`, plus the optional sketch), so an agent knows what to expect. Combined with the workflow guidance and read-only assurance, nothing essential for correct invocation 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 the baseline is 3. The description nonetheless adds meaning beyond the schema by explaining that the preview sketch is included 'unless preview is false' and framing preview as a speed tradeoff ('false returns text and data only, which is faster'), reinforcing the parameter's effect.

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 ('Shows one template up close') and enumerates exactly what it reveals: what it shows, its public page, the full scene, its review, and a preview sketch. It distinguishes itself from siblings by name, positioning it between list_templates and create_project.

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 explicit workflow placement: 'Use it after list_templates to check that a template fits the user's screenshots, then start a project from it with create_project (template_id).' Both the preceding and following tools are named with the condition that selects them, leaving nothing to inference.

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

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

Goes beyond the readOnlyHint annotation to disclose the URL's validity window (30 min), that no token is required, that the response includes a ready curl command, and size/duration limits (25 MB / 120 s). Missing only what happens on expiry or failure modes, but the key operational traits are covered.

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 eligibility envelope and benefit, then operational instructions. Slightly dense but every clause (limits, URL validity, parallel guidance, assign_to) earns its place. 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 2-param read-only tool with no output schema, the description covers purpose, constraints, response shape (URL + curl), and usage pattern. It omits URL expiry behavior and any auth context, but the annotations already declare readOnly/no-destruction.

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 parameter names are documented. The description adds value beyond the schema by explaining the assign_to effect ('put it on a screen at once') and implying how project_id scopes the URL. This is more than 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?

States a specific verb+resource ('returns a signed upload URL') and enumerates exactly which file types are eligible (screenshots, MP4/WebM screen recordings, music). It distinguishes itself from upload_media by making clear this is for disk-based files and from base64 paths.

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?

Explicit when-to-use ('files on your disk'), a direct comparison ('much faster than base64'), and operational guidance ('run one command per file — in parallel'). The '?assign_to=<device id>' hint tells the agent exactly how to route the upload.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, but the description adds that it takes no parameters and discloses the return shape ('a readable list plus compositions, references, palettes, formats, text_roles and text_regions'), which is valuable since there is no output schema. It does not mention caching, ordering, or size limits, so it stops short of a 5.

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

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

Front-loads the resource list, then usage, then alternatives, then return shape in three dense sentences with no filler. The parenthetical describing compositions is slightly long but earns its place by clarifying what a 'composition' is.

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 enumerates the return keys and the follow-up tools. A count of how many items typically return or whether the list is filtered is not stated, but for a read-only enumeration tool the coverage is adequate.

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?

Zero parameters, so there is no parameter semantics to document; the description correctly confirms 'no parameters'. Baseline 4 applies for a parameterless tool.

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?

Names a specific verb ('Lists') and enumerates the exact resource set: compositions, measured reference shots, palettes, format presets, text roles and text regions. An agent can tell precisely what it returns without opening anything else.

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 states when to use it ('before create_project or edit_scene to choose a composition, reference, palette or format') and names two alternatives with their selecting conditions (list_templates for finished named scenes, suggest_palette for screenshot-matched palettes). Nothing 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so 'Read-only, no parameters' is largely redundant. However, the description adds genuinely useful behavioral context unavailable elsewhere: the shape of the result (one line per device, plus a `devices` array with named fields), which matters because there is no 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?

Front-loaded with the core purpose and scope, then usage routing, then return shape. The sentences are dense but each carries distinct information; only the 'Read-only' clause duplicates the annotations.

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 takes on the burden of describing the return value and does so by naming the per-device fields (id, label, category, size_cm, screen_px, screen_aspect, recommended_screenshot_px, variants, browser_and_dock). Nothing an agent needs to call it or consume the result 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?

The tool takes zero parameters and the schema is an empty object, so there is nothing to disambiguate. The description correctly reinforces 'no parameters', which sets the right expectation for the caller.

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) and resource (every device model Showoff renders), then enumerates the categories covered (phones, tablets, laptops, displays, browser windows) and the fields returned per device. An agent can distinguish this from sibling list_* tools and from get_scene/create_project 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?

Explicitly names the downstream tools that consume its output (create_project, edit_scene's add_device/update_device, create_launch_video) and the purpose of the lookup (picking a device id or variant, or advising on screenshot dimensions). This is a clear when-to-use statement with the alternatives named.

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

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

Annotations already declare readOnlyHint, non-destructive and closed-world, so safety is covered; the description's 'Read-only, no parameters' largely repeats that. It does add genuinely useful context the annotations cannot, namely the exact return payload (folders with projects/projects_with_subfolders counts and top_level_projects), which matters since there is no 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?

Front-loaded with what the tool returns, then a dense but purposeful when-to-use clause enumerating the affected siblings. The sibling list makes the second sentence long, but every clause earns its place; 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 zero-parameter, no-output-schema listing tool, the description supplies purpose, trigger conditions, the exact return structure, and the intended downstream workflow. Nothing an agent needs to call 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?

The tool takes zero parameters, so the baseline is 4. The description correctly confirms 'no parameters' and the empty schema with additionalProperties:false leaves no ambiguity, though there is nothing further to explain.

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 folders of the user's Showoff projects') plus the concrete output shape (paths such as 'Showoff/Trailer'). This is easily distinguishable from siblings like list_projects or list_templates 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?

Explicitly names the downstream tools that consume the folder value (list_projects, create_project, edit_scene, create_launch_video, update_launch_video) and states the condition to call it: reuse an existing folder rather than inventing a new one. Nothing 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.

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

Annotations already declare readOnlyHint, destructiveHint and openWorldHint, so safety is covered; the description confirms 'Read-only' consistently. It adds ordering (most recently changed first), pagination mechanics and the shape of the response beyond what annotations provide, though it does not discuss rate limits or auth.

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 usage, then filtering, then return behavior — a logical order. It is dense and slightly run-on in the middle, but each sentence carries operational 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?

With no output schema, the description carries the burden of describing returns and does so ('projects', 'total', 'offset', and how to fetch the next page), plus ordering and filtering. Nothing an agent needs to call 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 coverage is 100%, so all five parameters are fully documented in the schema with enums, ranges and examples. The description only restates the filter and paging groups ('Filter by query, folder or kind; page with limit and offset') without adding syntax or meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource with scope ('Lists the projects of the user's organization, most recently changed first') and enumerates the returned fields. It explicitly distinguishes itself from list_folders, get_scene and get_launch_video, so an agent can route correctly 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 a concrete use case ('find the project_id the other tools need or to see what the user already made') and names the alternatives with their conditions (list_folders for the folder tree, get_scene/get_launch_video to look inside a project). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered and the description's 'Read-only' line is largely redundant. It does add useful behavioral context: no output schema exists, yet it discloses the exact return fields (templates with id, name, kind, duration, width, height, devices, categories, description, page_url) and how template_id feeds create_project.

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 examples before the workflow and alternatives, and each sentence earns its place (examples, trigger, follow-up, alternatives, return shape). It is slightly dense across four sentences but not padded.

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 compensates by enumerating the returned fields, and it covers the full lifecycle context (suggest -> inspect with get_template -> start with create_project, or build from scratch with list_compositions). Nothing an agent needs to select or call this tool 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% and both enums are self-documented ('image'/'film', the seven categories), so the schema already carries the parameter meaning. The description mentions kind only implicitly via 'stills and animations' and adds no syntax, defaults, or filtering nuance 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?

States a specific verb and resource ('Lists Showoff's template catalog') plus concrete scope ('finished, named scenes ... such as "Low Hero" or "Desk Duo"'). It names what it is not (get_template to inspect one, list_compositions to build from scratch), so an agent can differentiate it from siblings 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 an explicit trigger ('when the user wants ideas or a fast start'), a concrete follow-up workflow (suggest two or three by name with page_url, then create_project with template_id), and names the alternatives (get_template, list_compositions) with the conditions that select them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the sort order (newest first), the fields returned per entry, and that it mirrors the editor's history view.

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 compact clauses, front-loaded with the resource and ordering, then the return content, then the sibling pointer. No filler sentences.

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 characterizes what each history entry contains and the ordering, which is what an agent needs. It omits any note on result-size behavior tied to the limit parameter, a minor gap for a read-only listing 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 both project_id and limit (including default and 1-100 range) are fully documented in the schema. The description adds nothing about these parameters, which is acceptable but leaves it at 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?

States a specific verb+resource (version history of a project) and enriches it with scope details: newest-first ordering and the content of each entry (who changed it, when, what changed). It also distinguishes itself from restore_version by naming it as the sibling for the write-side action.

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 clearly implies the use case (inspecting history, matching what the editor shows) and routes the agent to restore_version for bringing a version back. It does not state explicit when-not conditions or other alternatives, but the context is unambiguous.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this while adding genuinely new context: what is rendered versus omitted (no lighting/materials), optional label overlays, per-project-type framing behavior, and that it 'never counts as an export'. This is behavior an agent could not infer from the 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?

The core purpose is front-loaded in the first clause, and the workflow/alternative guidance follows. The prose is dense and mostly earns its place, though the checklist enumeration and per-type rules make it longer than strictly necessary.

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?

Despite no output schema, the description states what comes back ('the sketch image and a short summary'), covers the workflow and the sibling alternative, and explains the non-obvious framing semantics for films, launch videos, and store sets. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3. The description nonetheless adds meaning beyond the schema by tying parameters to project types: `frames`/`time` apply to films and launch videos, launch videos default to the key moment of every block, and store sets use `language` and lay images side by side.

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 ('renders a fast schematic sketch of a project') and immediately scopes it against siblings by contrasting with export_image. An agent can distinguish it from export_image without opening either schema.

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

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

Explicitly prescribes when to use it ('after every create_project or edit_scene'), what to do with the result ('inspect the image critically against the checklist... then fix what you find'), and names the alternative with its condition ('use export_image only for the final rendered image').

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond that by explaining that nothing is lost, the pre-restore state remains in history and is itself restorable, the project name is unchanged, and open collaborators see the change live. This is exactly the behavioral context an agent needs before mutating shared state.

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 dense sentence that front-loads the core action and then layers the important semantic caveats. It is slightly clause-heavy, but every clause (new state, history preserved, name unchanged, live update) carries distinct 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 two-parameter mutation with no output schema, the description covers the semantics that matter: reversibility, scope of change, and visibility. It does not indicate what the call returns (new version id, updated project, etc.), which is the only notable 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 are already documented in the schema (project_id from create_project/list_projects, version_id from list_versions). The description restates the version_id source but adds no format, constraint, or edge-case detail, 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 ('brings ... back') and resource ('an earlier version of a project'), and immediately clarifies that the result is a NEW current state rather than a historical rewind. It also names the sibling that supplies the input (list_versions), so the agent can distinguish this from retrieval tools without opening either schema.

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

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

It gives an explicit guardrail: 'Only when the user asks for an earlier version,' which tells the agent when not to reach for it. It also routes the agent to list_versions for the version_id. What's missing is a named alternative for the adjacent case (e.g., what to use if the user wants to view a past version instead of restore it).

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

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

Annotations declare readOnlyHint=true, and the description reinforces 'Read-only.' Beyond that, it discloses non-obvious behavior: it surfaces warnings that edit_scene saves anyway, every finding has a severity and a fix with ready-to-send edit_scene ops, and results are ordered errors first with a pass/fail verdict. These are substantive behavioral facts not derivable from annotations or 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?

Front-loads the core purpose and scope, then routes to alternatives, then states return shape. Dense but every sentence carries information. Slightly long due to the breadth of checks listed, but none of it is padding.

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 a read-only tool with no output schema and 2 params at 100% schema coverage, the description supplies everything an agent needs: purpose, alternatives (finish, render_preview, edit_scene), strict-mode semantics, and return structure (findings, errors first, pass/fail). Nothing material 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 coverage is 100%, so both parameters are already documented. The description nonetheless ties `strict` to the finish tool's semantics and explains that unfinished parts become errors — reinforcing the schema's own description. It does not add new parameter meaning beyond what the schema provides, but it's a helpful cross-reference. Baseline for 100% coverage is 3; the cross-tool contextualization earns a 4.

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 ('runs the full art-direction review') and resource (project/scene), and enumerates the exact checks performed: collisions, angles, floating vs resting devices, text overlap, cropping, contrast, composition, color. Clearly differentiated from siblings like render_preview and finish by naming them 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?

Provides explicit when/when-not guidance: 'Use it while building to see every finding, including warnings edit_scene saves anyway; use finish once at the end for the final check, and render_preview to look at the result.' The `strict` parameter's role (final-check mode as in finish) is also explained. This is textbook alternative-routing.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real substance: palettes are pre-reviewed for contrast against devices/texts, results are best-first, and it hands back a ready-to-send edit_scene op. It doesn't state cost/latency or whether the suggestion is cached, so not quite a 5.

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

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

Front-loaded with purpose, then timing, then the apply path and return shape. It runs a bit dense in the middle sentence, but every sentence carries information an agent needs; nothing is redundant 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 compensates by naming the returned fields (accent, palettes with id, name, gradient, review result, ready-to-send op) and the ordering. Combined with annotations and full schema coverage, an agent has everything needed to call and consume the result.

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 reinforces that `accent` is an override for the derived accent color, but adds no syntax or constraint beyond the schema's '#hex' example. 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 and resource ('suggests background palettes for a still or film project') plus the derivation source (accent color of screenshots). It also distinguishes itself from list_compositions, which 'has the full fixed palette list,' so an agent can 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?

Gives an explicit ordering rule ('once the screenshots are on the screens and before adding texts') and names the alternative source of palettes (list_compositions). The follow-up path (apply via edit_scene) is spelled out too.

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

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

Annotations declare it is a non-read-only, non-destructive mutation, so the safety profile is covered. The description adds real behavior beyond that: merge semantics for block edits (null removes a field, another type restarts the block), that a new device re-checks blocks and unfit transitions fall back to natural ones, and that it returns the updated video with its render page and what is still missing. It does not discuss permissions or rate limits, keeping it at 4.

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 purpose and the when-to-use routing before the long enumeration of editable fields and edge cases. The middle run-on sentence packing all edit modes is dense but earns its place given 22 parameters; nothing is padding, though it could be split for readability.

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 very complex mutation tool with no output schema, the description covers purpose, alternatives, merge/fallback behavior, and the return payload. The inclusion of the sibling routing and the disk-screenshot curl fallback make it adequate; minor gaps remain around error/validation behavior.

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 22 parameters in depth; baseline is 3. The description adds a little semantic routing (which fields are update modes, the 1-based block index from get_launch_video, the curl flow for disk screenshots) but largely restates schema-level facts.

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 ('Changes an existing launch video') and immediately enumerates the mutation modes (blocks, block edit, name, accent, device, look, background, folder, screenshots, music). It distinguishes itself from siblings by naming create_launch_video and duplicate_project as the tools for new/variant videos.

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 'Use it for every edit to a launch video' and routes the agent: 'Use get_launch_video first for block indexes and slots', create_launch_video for a new video, duplicate_project for a variant. It also states the constraint that lines/tagline without blocks rebuild the standard film, so the agent knows which combination to pick.

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

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

Annotations declare write (readOnlyHint=false), openWorldHint=true, destructiveHint=false, so the safety profile is mostly covered. The description still adds real behavioral context the annotations don't: analysis side effects, the optional device-screen assignment, that base64 writes are minutes-slow and get truncated, and that songs become music in a launch video.

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 primary behavior and ending with the routing warning. It is on the dense side and repeats some base64 warnings already in the schema, but every sentence carries 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 mutation tool with no output schema, the description covers what gets created and what analysis happens, but says nothing about the return value (e.g. a media id to reference later) or whether re-uploading the same URL deduplicates. These are minor gaps against an otherwise complete definition.

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 meaning the schema lacks: the url parameter is documented for images only in the schema, yet the description clarifies it also accepts audio (MP3, M4A, WAV) and explains the url-vs-data_base64 tradeoff (small base64 only, minutes-slow, truncated). That is genuine added semantic value.

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 (adds image/audio to the project's media library) and enumerates the resulting behaviors (color/aspect analysis, tempo/drop analysis, optional device assignment). It also explicitly distinguishes itself from the sibling get_upload_link, so an agent can tell them apart without opening either schema.

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

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

Gives explicit routing: use this tool for public URLs or tiny base64, use get_upload_link for files on your own disk, and never pipe base64 through a shell. The when-to-use and when-not-to-use conditions are both spelled out with the alternative named.

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