Clueso

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

Beyond the annotations (which only declare non-read-only, non-destructive, open-world), the description discloses cost (generated images consume AI credits "like generate_media's"), latency ("takes a few seconds"), and a full async contract: a GIF still rendering after ~20s returns `status: "processing"` plus a `job_id` and lands in the article later. It also discloses that `replace` removes the old screenshot and states exactly what is returned (`screenshot_id` and the new `article_version`).

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?

Structure is strong: a front-loaded sentence covering placement and return values, then two scannable bullets keyed by `kind`. It is slightly long and repeats a few facts already present in the schema property descriptions (style_id/aspect_ratio applicability, aspect_ratio default), which keeps it off a 5.

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

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

With 11 parameters, no output schema, and a mix of sync/async behavior, the description covers everything needed to call correctly: placement precedence, per-kind required params, the video-clip precondition, credit cost, and the async job fallback with its follow-up tool. Return values are described inline, compensating for the missing 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 100%, so the baseline is 3; the description earns above that by documenting cross-parameter conditionals the schema lists only per-field (`prompt` interaction with `style_id`/`aspect_ratio`, default 16:9), the origin of opaque IDs (`mup_…` from upload_file vs a Clueso upload_id), and practical guidance that generated text is often misspelled. Some of this duplicates the schema text rather than adding new meaning.

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

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

The description opens with a specific verb and resource ("Add a screenshot or GIF to the article") and immediately explains the three mutually exclusive placement modes (`after`, `replace`, otherwise append). It is clear what the tool does, but it never contrasts itself with the closely related sibling `update_article_media`, leaving the add-vs-modify decision to inference.

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

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

Usage is spelled out per mode: `kind="image"` lists all four capture/attach/generate sources and when each applies, `kind="gif"` states the required `timestamp`+`duration` and the precondition that the project must have a video clip. It also routes the agent to the right companions for adjacent steps (`upload_file` for `mcp_upload_id`, `generate_media` for `source_url`, `find(type='image_gen_style_packs')` for `style_id`, `get_media_job` to follow a pending job).

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 it is a non-read-only, non-destructive, closed-world mutation; the description adds far more: the project-wide conflict domain requiring serialization, that uploads get persisted to the project media panel, that non-find sources have duration probed, and that Freesound handles are opaque and resolved server-side. Most importantly it discloses that the default guide_end_time is captured at call time and will NOT auto-extend, which is exactly the kind of silent behavior that trips agents up.

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, exclusions, and the sibling alternative before any parameter detail, then cleanly split into per-type bullets and a separate concurrency warning. It runs long for a tool with full schema coverage and repeats the Freesound opaque-handle point in both bullets, plus re-lists optional parameters the schema already documents.

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 14-parameter mutation tool with no output schema, the description covers everything an agent needs to call it safely: source provenance rules, per-type required fields, trimming versus placement time semantics, defaults that behave surprisingly, and the serialization requirement. Nothing material about correctness of the call is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds real meaning on top: it spells out per-type requirements (music requires src; sfx takes src/name/source_duration or a legacy sfx_key), clarifies that music_start/end_time trim within the SOURCE while guide_start/end_time position in the timeline, and supplies a derivation rule not present in the schema (guide_start_time = element start + the cue's t). Minor overlap with the schema's own wording keeps it short of a 5.

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 ("Add a music track or sound effect that plays as a project-level audio layer over all clips") and immediately names the boundary conditions that distinguish it from siblings: it does not consume a clip slot, background music goes here, and per-element sound belongs to the element, not its page. It also explicitly routes the alternate case to add_clips(kind='video'), so an agent can separate add_audio from add_clips 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-to-use framing (background music/soundtrack under an existing timeline), an explicit when-not (an HTML animation's sound does not go in its page), and a named alternative with the condition that selects it (add_clips with an audio mime_type for a sequential clip with auto-transcription). Concurrency guidance adds a second usage constraint — serialize, never run in parallel with any other mutation on the same project.

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 far beyond the annotations, which only say non-readOnly/non-destructive/closed-world. It discloses the async background pipeline (download → transcribe → insert), the 24h cache that makes later calls synchronous, the aspect_mismatch refusal, gap restoration semantics (`restored_gap_seconds`), and a whole-project concurrency/serialization rule that annotations cannot express.

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

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

Front-loaded with a one-line summary and then a clean per-`kind` bullet structure that mirrors the enum, so scanning is fast. It is long and carries a few dense parenthetical asides (re-cut clock semantics, auto_elements cache behavior), but with 15 parameters and four modes little is wasted.

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

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

Covers mode selection, prerequisites (upload_file), positioning, side effects, failure modes, and concurrency — nearly everything needed to call it correctly. The one gap is that with no output schema, it never says what comes back (e.g. created clip IDs or job handles), which an agent chaining follow-up edits would want.

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 meaning on top: cut seconds are on the run's own clock (0 = start of first clip), `text_overrides` map to text elements in document order with empty values keeping placeholders, `after_clip_id` is REQUIRED for templates but optional elsewhere, and '' inserts at the front for video.

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+resource ('Create new clips on a project') and immediately decomposes the tool into its four source modes via the required `kind` parameter. Each mode is described concretely enough that an agent can tell which one it wants without opening the schema.

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

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

Explicit routing away from siblings: overlay video onto an existing clip → add_elements(element_type='video'), background music → add_audio, clip templates → find(type='clip_templates'). Also gives when-not-to assumptions (create_project already makes clip 0) and an explicit instruction to ask the user rather than guess `after_clip_id` for templates.

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?

The description goes beyond annotations by disclosing that the comment is attributed to "Clueso AI" (a behavioral trait), and explains the threading behavior: replying makes the note resolvable, while a fresh top-level comment adds noise. It also states that when replying, the clip pin and timestamp come from the parent, so clip_id/clip_timestamp should be omitted. Annotations only provide readOnly/destructive hints, so this added context is valuable.

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 (about 120 words), front-loaded with the core action, and organized into logical sections: main purpose, use cases (project vs. clip), and reply guidance. No filler or repetition; every sentence adds 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?

Given the tool's moderate complexity (5 parameters, no output schema), the description covers the key usage patterns, parameter relationships, and workflow prerequisites (reading with get_comments). It does not describe response/return values or error behavior, which is a minor gap, but overall an agent has enough context to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema already documents all parameters (100% coverage), the description adds crucial inter-parameter semantics: it explains clip_id is omitted for project-level comments, clip_timestamp is only used when clip_id is provided, and parent_comment_id should be taken from get_comments and implies leaving clip_id/clip_timestamp off when replying. This is more actionable than the schema alone.

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: "Post a review comment on a project, attributed to 'Clueso AI'." It immediately distinguishes from related tools like get_comments by stating its write purpose and clarifying project-level vs. clip-pinned comments.

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 says when to use the tool ("Use this to leave feedback, suggestions, or notes"), and provides clear guidance on when to reply vs. start a new thread: "Pass parent_comment_id to REPLY to an existing comment rather than open a new thread." It also directs the agent to read existing comments with get_comments first and warns against adding noise, which is a clear alternative/usage boundary.

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 it is a non-destructive, non-open-world write; the description supplies what they cannot — per-item ordering with partial success, the CLIP's element list as the conflict domain, that a rejected concurrent call writes NOTHING and must be re-read and re-applied, that a group cannot be repositioned after creation, and that grouping changes z-order by pulling members to the lowest slot. None of this contradicts the annotations (destructiveHint=false is consistent with partial-success adds and additive z-order placement).

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 highest-value advice (batch, hoist into defaults), but at roughly 800 words it repeats schema-documented material verbatim (y_anchor, insert_at, element-type quirks) and buries key rules in dense paragraphs — the group/insert_at refusal logic takes several re-reads. The length is defensible for the tool's complexity, but not every sentence earns its place against the schema.

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

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

Covers everything an agent needs for a 14-type, nested-object batch writer with no output schema: what comes back (per-item result, element_ids, end_state, avatar render/cost, not_carried, errors under every returning mode), how coordinates and anchor origin behave per type, and the concurrency ceiling. Nothing material is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so 3 would be the floor, and the description goes beyond it on the highest-risk params: the `defaults` hoisting model with one-level type_data merge and per-key item override, `returning` framed as analogous to get_clip's `select`, `continue_from` carrying end_state/transform so a keyframe continues without a jump, and the group+insert_at interplay where the reference's location decides whether the element or the group is positioned. It restates a fair amount that the schema already carries (y_anchor, element-type quirks), which keeps it off a 5.

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

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

States a specific verb and resource ('Add many elements across one or more clips in a single tool call') and immediately positions itself against the per-element path ('Replaces the per-element tool — always batch'). An agent can distinguish it from update_elements and add_clips without inspecting 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?

Explicit routing guidance throughout: 'Use after calling get_element_schema to confirm the type_data shape', native vs HTML animation decision rules ('charts, product UI, structured diagrams...'), component reuse via component_id vs base_component_id for a new variant, find(type='element_components') to locate them, and continue_from for cross-cut continuity. It also names concrete non-alternatives for concurrency (update_clips, add_clips, remove_clip, split_clip, add_audio, update_project).

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?

Beyond the minimal annotations, the description discloses matching behavior (case-insensitive, punctuation-stripped, first match by default), occurrence indexing semantics, timestamp mapping when generated_timestamps exist, and the word_not_found error with an excerpt. This gives the agent a strong mental model of tool behavior.

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

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

The description is organized into clear sections: use cases, matching behavior, and constraints. Every sentence carries useful information, and the most important purpose and usage guidance appear first. Despite its length, nothing feels redundant.

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 7 parameters, no output schema, and minimal annotations, the description covers prerequisites, matching rules, timestamp handling, and error recovery. The only minor omission is the success return shape, but that is not necessary to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds meaningful semantics: occurrence is 1-indexed and required for repeated words, timestamp_seconds is clip-relative and auto-inverse-mapped, and clip_id vs clip_index selection behavior is clarified. This goes well beyond the schema's field 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 opens with a specific verb and resource: 'Insert one sync marker on a clip's transcript.' This clearly distinguishes it from the sibling auto_sync, which performs automatic sync, and from other clip-editing tools like split_clip.

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 when-to-use conditions: the user is explicit about where to pause/cut, or auto_sync missed a step. It also states the key constraint that the clip must be a video clip with a source recording, and warns when the word is not found, which effectively tells the agent when not to proceed.

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 establish read-only, non-destructive behavior, but the description goes well beyond: provider auto-fallback so an empty `words` is genuine silence, the 40% speech-share threshold and its known false negatives, ~10ms drop accuracy, empty beats_ms for non-music, and the cheap-dispatcher note. These are exactly the caveats an agent would otherwise misread as failure.

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 verb and a 'Modes:' header, then one bullet per mode that pairs output shape with the decision it enables — no filler. It is long, but the length is bought by seven modes and a missing output schema; the only slack is a few rhetorical asides that could be trimmed.

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 seven return shapes, the description compensates fully: each mode documents its fields, units, and edge cases (empty words, empty beats, false instrumentals). Source selection and time-window cropping are both covered, so nothing needed 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 already 100%, so the baseline is 3; the description still adds meaning by stating that range_start_ms/range_end_ms crop the analysis window and that exactly one of mcp_upload_id or file_url must be supplied, with file_url scoped to public/Clueso CDN sources. It also ties energy_options.samples_per_second to the resulting db array resolution rather than just restating the bound.

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 (analyze) and resource (audio file), then enumerates all seven modes with their distinct outputs. An agent can tell exactly which capability this covers and distinguish it from upload_file, extract_audio, or get_clip without opening the schema.

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

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

Every mode carries its own 'use for' statement (caption timing, auto-trim, beat-aligned zooms, picking a mode, animation cues). It also names alternatives and the conditions that select them: get_clip's voiceover_words for seconds instead of ms, find(type='music') for the suggested search query, transcript instead of features when words matter, and add_audio for source_duration.

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 say destructive/non-read-only; the description adds the crucial async contract ('Returns once started; markers land a few seconds later'), the concrete mutation (marker nodes inserted into the transcript), and the full set of skip outcomes with their payload fields (held_by, clip_id/duration_label). It is consistent with destructiveHint=true, since transcript content is modified.

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 action, then the prerequisite, then the skip matrix, then the async return behavior. Dense but zero filler; the compact quoted stop-codes ('clip_busy' + held_by) pack a lot of routing information into few characters.

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 return contract and does it ('returns once started'), plus polling guidance and failure semantics. An agent has everything needed to decide, call, and follow up correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented, and the baseline would be 3. The description adds eligibility semantics beyond the schema: the clip must have a source recording and must fall within a roughly 5-minute window, which constrains which clip_id is valid.

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 ('Run the agentic auto-sync pipeline on a clip') plus the mechanism ('detects natural sync points (UI changes, narrated steps) and inserts sync-marker nodes into its transcript'). The 'auto-detect' framing implicitly separates it from the manual sibling add_sync_point.

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 prerequisite ('Required before voiceover TTS on video clips'), enumerates the conditions under which it should not run, and routes the agent in each case: audio_extracted means read-only, clip_busy means retry later, clip_too_long means use split_clip then re-run. It also tells the agent to poll get_clip before TTS.

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 non-read-only and non-destructive; the description supplies the real behavioral load — validation refusals with an allowed range, the 0.1s minimum, no-overlap and in-clip constraints, translation-mode restrictions (edit retargets translated text, split refused), custom timing being invalidated by voiceover regeneration, and per-clip vs all-clip concurrency semantics. None of this is recoverable from the 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-loaded with the core purpose, then organized as a list-first procedure followed by per-action bullets and a trailing Rules/Concurrency block, so it is scannable despite its length. A few parenthetical asides (e.g. the long-project translation advice) are helpful but push it toward the verbose end of acceptable.

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?

A 12-action, 10-parameter tool with no output schema demands a lot, and the description covers the discovery path (what list returns), each mutation's effect and reversibility (reset, timing_reset, merge only undoes split), failure modes, and cross-clip side effects. Nothing an agent needs in order to call it correctly appears to be 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?

Although schema coverage is 100%, the description adds meaning the schema cannot carry: split_word_index is the word that STARTS the second caption (with the block-word arithmetic spelled out), merge takes the SECOND caption's start_word_index, times are seconds from clip start, and clip_index is omitted for translate/language to hit every clip. These are exactly the indexing and unit ambiguities that cause wrong calls.

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+resource pair ("Read and edit a clip's CAPTIONS") and immediately scopes it to what, where boundaries fall, timing, manual captions and translation. It explicitly separates itself from voiceover_batch (spoken audio), export_project (burn-in) and translation_glossary (rules/glossary), so an agent can distinguish it from all relevant siblings.

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

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

Gives an explicit entry procedure ("Start with action=\"list\"") and then per-action guidance including when to prefer manual_add (clips with no voiceover, gap filling) and when merge is valid (only when mergeable:true). It also names the correct sibling for the adjacent need (voiceover_batch for what is spoken, set_voice for voiceover language), which is the strongest form of 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 carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description builds on that with the return contract ("Returns one mcp_upload_id per file"), the batch scope of the token ("the token covers all files they dropped on the page"), and recommended call timing. It adds real behavioral context beyond annotations, though it stops short of specifying container format or pagination. No contradiction 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 sentences (~48 words) with zero filler. The first sentence states the core purpose, and each subsequent sentence earns its place: return shape, routing to consumers, call timing, and token scope. Nothing repeats annotations or schema content.

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

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

For a low-complexity signature (1 param, no output schema), the description covers the trigger condition, the required token, the key return value (one mcp_upload_id per file), and the downstream handoff. The minor gap is the absent output schema: the exact return container shape and the criteria for choosing "the appropriate tool" are left unspecified, creating slight routing ambiguity. Annotations covering safety keep this close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already explains where the token comes from (upload_file request_hosted_upload: true). The description adds meaning the schema lacks: "the token covers all files they dropped on the page" clarifies that a single token maps to multiple files, which is essential semantic context for using the parameter correctly. This raises the score above the baseline.

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

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

The description opens with a specific verb+resource: "Fetch all files the user uploaded via the hosted upload page," naming both the action and the exact scope. It clearly differentiates itself from siblings by framing the tool as the retrieval step of an upload workflow, distinct from the add_* consumers it explicitly names.

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?

"Call this once after the user confirms they are done uploading" is an explicit trigger condition with a frequency hint ("once"). "Pass each to the appropriate tool (add_clips, add_article_media, etc.)" explicitly names the downstream alternatives, telling the agent what to do with the result and when to use those siblings instead.

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 mark this as a non-read-only, non-destructive creation tool, and the description adds substantial behavioral context: source-guide extraction can take minutes, decision lists in the reply should be surfaced to the user, and brand_locked changes whether projects retain the clueprint's branding. No annotation contradictions.

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 definition and scope in the first sentence, then groups structural details, extraction behavior, decision handling, and brand_locked semantics into readable paragraphs. It is long but mostly earns its space for a complex creation tool; some inline enumerations make it denser than 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?

Given no output schema, the description explains the important reply behavior by naming the non-empty decision lists that must be surfaced to the user and recorded via update_clueprint. It also covers folder structure, extraction timing, and brand-locked behavior, leaving little ambiguity for an agent invoking 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?

Schema coverage is 100%, so the baseline is 3. The description still adds meaningful semantic detail for brand_locked (including the co-marketing use case) and source_guide_ids (clip-by-clip extraction and latency), going beyond the schema's brief field 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?

Starts with a specific verb and resource: "Create a new clueprint," then immediately defines a clueprint as a reusable video template with structured design notes, rules, and screenshots. It clearly distinguishes clueprints from projects by explaining the format versus brand-kit relationship.

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

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

Explains when source_guide_ids triggers clip-by-clip extraction and tells the agent to ask the user about decision lists and record them with update_clueprint(decisions). It also clarifies the create_clueprint vs create_project distinction, but does not explicitly state when not to use this tool.

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 well beyond the annotations by disclosing the case-insensitive deduplication rule and the resulting already_existed=true contract, which explains why the tool is safe to call as an upsert-style 'ensure'. It also enumerates the return payload, adding behavioral context that openWorldHint=false and idempotentHint=true cannot convey.

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

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

Front-loads the core action, then the dedup/return contract, then cross-references to related tools. 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?

Even without an output schema, the description spells out the returned fields (folder_id, name, parent_folder_id, already_existed) and the idempotency semantics, so an agent has everything needed to call it correctly and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: name matching is case-insensitive and duplicates are suppressed, and parent_folder_id omission means the workspace root ('Omit for the workspace root'). These are semantic details beyond the schema text.

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

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

States a specific verb and resource ('Create a folder in the workspace') plus its scope ('optionally inside another folder') and intent ('to organize projects'). This clearly distinguishes it from sibling creation tools such as create_project and create_clueprint.

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 concrete follow-up and discovery guidance by naming sibling tools: 'Put projects in it with create_project(folder_id=...)' and 'List existing folders with find(type='folders')'. It also indicates the safe 'ensure a folder exists' pattern, though it does not explicitly state when not to use it (e.g. the project/clueprint alternative).

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 non-read-only, non-destructive, non-open-world, so the description carries the real behavioral load and does it well: background voiceover generation (~seconds per clip), clip lengths derived from speech or from the uploaded audio, transcription producing script and captions, and the workspace-default brand kit inheritance with 'none' as an opt-out. It also notes the editor/admin permission requirement for setting a kit, which annotations cannot express.

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

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

Core creation behavior and return values are front-loaded, and the clueprint/brand-kit/voiced sections are ordered by decision the caller has to make. Some content duplicates the schema (folder and brand-kit ID discovery instructions appear in both), and the clueprint paragraph is dense, but no sentence is pure 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 six-parameter, zero-required, side-effecting creation tool with no output schema, the description covers return shape, initial project state, background/async behavior, permission constraints, and defaults. An agent could call it correctly and know what to do next without opening another tool 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; the description earns above that by explaining what the values actually do — script paragraphs map one-to-one onto blank clips whose lengths follow the speech, audio becomes clip 0's voiceover and sets its length, and brand_kit_id has 'default' and 'none' special values with inheritance semantics. Only the title and description parameters get no added meaning beyond the schema.

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

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

Opens with a specific verb and resource ("Create a new blank Clueso project") and immediately states what is returned (projectId, initialClipId) plus the initial state (one blank clip at index 0). This separates it from siblings like duplicate_project and create_clueprint, which also produce projects but from existing material.

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 routes follow-up work: update_clips to resize clip 0, add_clips(kind='blank') to append, add_elements for content, add_audio for music. It also states the script-vs-audio exclusivity ("one or the other") and names find(type='folders')/find(type='brand_kits')/create_folder as the sources for the ID parameters.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses meaningful behavioral traits: S3 assets are re-hosted into the target namespace, the duplicate is independent of the source, deleting the source project later won't break it, the conflict domain is the entire target project, and it returns the new clip_id and final index. No contradiction 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?

The description is well-structured with bullet points, front-loads the core purpose, and every sentence serves a clear function (modes, insertion, output, concurrency). It is informative without being bloated.

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 cross-project side effects and concurrency constraints, the description covers all necessary operational aspects: mode selection, asset re-hosting, insertion position, return value, and serialization requirement. An agent has enough context to invoke the tool correctly without an 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 description coverage is 100% and each parameter is already described in the schema. The description restates the same-project vs cross-project combinations and after_clip_id behavior, which adds some clarity about parameter relationships but does not introduce 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?

The description states a specific verb ('Clone'), a specific resource ('one clip'), and the destination ('target project'), and distinguishes same-project from cross-project duplication. This clearly separates it from siblings like duplicate_project (whole project) and add_clips (adding new clips).

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

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

The description gives explicit parameter combinations for same-project vs cross-project use and explains insertion behavior with after_clip_id. It also includes a strong concurrency warning. However, it does not explicitly name alternative tools or state when not to use this tool, so it misses the highest bar for exclusion guidance.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the key behavioral trait that the duplicate has its own S3 namespace and is therefore independent of the source. It also states return values and warns about concurrency, which is exactly the kind of context an agent needs.

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 compact, front-loaded with the core purpose, and uses a short bulleted 'Defaults' section to organize conditional behaviors. The concurrency warning is a single necessary sentence. No filler or redundancy.

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

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

For a tool with no output schema, the description correctly states what is returned (new project's id and title). It covers source selection, folder targeting, title defaults, copy independence, and concurrency safety, leaving no crucial operational gap for invoking the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters, so a baseline of 3 applies. The description adds meaningful nuance beyond the schema: the conditional title behavior when new_title is omitted, the distinction between omitting folder_id and passing an empty string, and the effect of an explicit non-empty folder_id.

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 — 'Clone an entire project' — and enumerates what is copied: every clip, voiceover, asset, and metadata field. It clearly differentiates from the sibling duplicate_clip by emphasizing the whole-project 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?

The description gives clear operational guidance: default title behavior, folder placement behavior, and an explicit concurrency constraint to serialize against other mutations on the same source_project_id. It does not explicitly name alternatives like create_project or duplicate_clip, but the scope statement makes the intended use apparent.

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?

Beyond the annotations, it discloses that saves are one revision, that failing saves are kept but move no uses, that passing saves move project uses in one undo step, that dry_run returns a preview token, and that breaking changes require confirm_breaking. It also explains checkpoint versioning and canvas Mograph upgrading.

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 long but justified by 22 parameters and nested objects, and the core action is front-loaded. It is dense and occasionally telegraphic, with some repetition of schema-covered details, but the sectioned layout keeps it navigable.

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 having no output schema, it explains the reply fields (rev, probe, checks/errors, files_changed, uses_moved, note), detail modes, preview results, and refusal outcomes. For a complex edit-and-place tool, an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries most parameter detail. The description still adds useful cross-parameter semantics: accepted file-change shapes, atomic all-or-nothing matching, upload_id linkage to upload_file, and place/preview behavior.

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

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

The first sentence states a specific verb and resource: changing an HTML animation's site in one revision, with linting, checking and probing. It also distinguishes the tool from update_elements by assigning placed-element parameters, actions and cues to that 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?

It explicitly instructs the agent to read get_design_guide({topic: "pages"}) before writing or editing a page, explains the preview/dry-run choices, names stale_base/check_failed/breaking_unconfirmed refusals, and redirects placed-element changes to update_elements.

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 well beyond the annotations (readOnly=false, openWorld=true, destructive=false): returns immediately with an export_id, renders ~5 min in background, is refused while a speech/sync/build job holds the project, and resolution/fps above plan are silently capped. The one gap is that it never says what happens to a previously existing export or whether repeated calls stack up jobs.

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 imperative workflow instruction, then bulleted per-parameter sections — good structure and almost no waste. It is long, but given 7 parameters with non-obvious interactions the length is largely earned; a few clauses (the "no voiceover-only file" aside) could be tightened.

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 tells the agent what comes back (export_id immediately; download_url or embed_url later via get_export), covers defaults, plan caps, and the exact precondition that causes refusal. Nothing needed 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 already 100%, but the description still adds real semantics: destination="embed" is permanent and updates in place behind the same URL (with an editor/admin requirement), format="mp3" is download-only and ignores resolution/fps/captions, and captions are ignored entirely for embeds. That is behavior no schema enum can express.

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+resource ("Start a video export of the project") and immediately scopes the behavior as asynchronous. It also differentiates itself from siblings it could be confused with (get_export, get_embed, run_script) rather than leaving the agent to infer the boundary.

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

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

Explicitly prescribes the correct agent behavior (start it, tell the user, stop) and names the anti-pattern to avoid — polling get_export or holding run_script open. It also states the condition for the follow-up call ("Call get_export only when the user asks for the link") and routes already-published projects to get_embed instead.

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?

Far exceeds the annotations: it discloses sync behavior through later edits (clips moving, cuts, splits), the voiceover lock (voiceover_batch skips it, update_clips voiceover_volume errors), the reversible restore path, and the whole-project mutation concurrency constraint. destructiveHint=false is consistent with a reversible operation, so no contradiction.

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 outcome, then uses tight bullets for editing, sync, locking, restore, workflow, errors, and concurrency. It is long and dense, but nearly every sentence carries operational information an agent needs; minor compression is possible in the sync bullet.

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 mutating tool with no output schema, it covers return value (music_id), state changes, side effects on other tools, error conditions, and concurrency. 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, but the description adds real meaning beyond the schema: restore not only flips audio back to 100% but leaves the extracted track in place (remove separately), and it identifies where the track's src comes from via get_project.audio_tracks. clip_id vs clip_index precedence is 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+resource and the exact resulting state: the clip's audio (recording or voiceover) becomes a separate track and the clip goes silent, returning a music_id. It distinguishes itself from update_audio, analyze_audio, and remove_from_project by naming each and its role, so an agent can route without opening other 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 when-to-use (the keep-audio/swap-visual workflow as a numbered procedure), when-not-to-expect-success (errors if already extracted, no audio, or speech generating), and the alternatives for adjacent tasks (update_audio to shape, restore to undo, remove_from_project to discard).

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 openWorldHint=true, yet the description still adds substantial non-obvious behavior: the ~200MB source cap that fails tiers above 1080p, Freesound's `src` being an opaque handle rather than a playable URL, silent Inter fallback for unknown font families, and page-through warnings when clueprint lists are sliced. These are exactly the failure modes an agent needs surfaced 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?

The lead sentence and the Returns line are well front-loaded, but the body is a very long block of nested parentheticals stopped by semicolons, and the Filters section largely re-states what the schema already documents for `id`, `query`, `provider`, `detail`, and `source`. Much of the per-type detail is genuinely needed; the duplication with structured fields is not.

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 36-parameter, 20-type multiplexer with no output schema, the description covers the return envelope ({ type, count, items }), the paging semantics, per-type result shapes (clip_templates sections, video_files tiers, brand kit sections), and how to feed returned ids into consuming tools. Nothing an agent needs in order to call it correctly appears to be 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 would be 3, but the description genuinely extends it — it explains that `query` means semantic search for stock, relevance ranking for clueprints, and a name substring for everything else, and that `tags`/`tag_match` combine in a specific way. It also clarifies `limit` caps every type while stock shortlists have no further pages, which the schema does not state.

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+resource ("Find any resource in Clueso by type") and enumerates the exact type taxonomy, so an agent knows precisely what universe it covers. It also positions itself as "one tool for listing and searching across the workspace," which implicitly separates it from the get_* siblings, but it never names those siblings to make the boundary explicit.

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 guidance throughout: provider choice by strength per media type, "music/sfx options for the user → search BOTH in parallel," "picking one yourself → 'clueso' first," "never switch sets" for icons, and "check here before building a layout on a brand typeface." Alternatives are named with the condition that selects them, leaving little 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 only say readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does it: asynchronous creation with a stable element_id, the exact poll loop (get_clip(select:['busy']) until busy is empty), credit consumption per call, and the fact that writes via update_elements are likely refused while generation holds the element. It also discloses a non-obvious side effect (voiceover_text triggers speech generation and must carry <SYNC_MARKER N> tokens) and that `group` is silently overwritten rather than accepted.

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 and well-sectioned with bold headers (kind, TIMING, Tip), which helps. But it is long for a description and contains an aside that serves no invocation purpose: '(This previously said to watch the `phantom` flag; `phantom` has never been a key get_clip returns, so there was nothing to poll.)' is changelog commentary the calling agent does not need.

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 19-parameter, nested-object, asynchronous, credit-consuming tool with no output schema, the description covers everything an agent needs to call it correctly and interpret the result: how to confirm the render landed (empty `busy`), expected latency bands, and the follow-up pattern (ungrouped first, then update_elements with `group`). 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 baseline would be 3, but the description adds real partitioning the flat 19-param schema does not: which fields are image-only vs animation-only, that animation_setting must be set at creation time rather than patched afterward, and that reference_image_url / mcp_upload_id are the grounding path. It does not add format or syntax detail beyond the schema for the geometry params (x/y/width/height), which keeps it off a 5.

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 concrete verb+resource and immediately splits it into the two supported modes ('kind="image": text-to-image' vs 'kind="animation": canvas-code animation'), each with its own parameter set. It also explicitly names the sibling it is not ('For uploaded photos / logos / icons / GIFs, use add_elements with element_type='image''), 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-to-use ('generated', 'AI', 'create me a' visual), explicit when-not (uploaded assets → add_elements), and the internal fork between image and animation. It also pre-empts the most likely mistake by forbidding re-invocation: 'do not call generate_media again for it, because each call is a new generation and uses credits again.'

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 readOnly/non-destructive, so the safety profile is covered. The description goes beyond that by disclosing the placeholder conventions (<SCREENSHOT {id}>, <EMBED {id}>) that will appear in the returned markdown and by naming the returned fields — genuinely useful behavioral context that annotations cannot 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?

Three sentences, front-loaded with the core action and output format; each sentence adds distinct information (format, placeholders, return fields). Slightly dense with two placeholder idioms in one sentence, but no wasted text.

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

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

With no output schema, the description correctly takes on the burden of describing the return value (markdown text, screenshot ID list, article_version), which is the key missing piece an agent would otherwise lack. It is complete for a simple one-parameter read tool, though it could note whether screenshot IDs map to a companion fetch 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% for the single parameter (project_id), so the schema already carries the parameter documentation. The description adds nothing about the parameter, which is acceptable at baseline but no better.

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

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

States a specific verb and resource ('Get the article content as markdown') and immediately explains the representation the agent will receive. It doesn't explicitly differentiate itself from siblings like get_embed or get_clueprint, though 'article content' vs. embed content is reasonably distinct.

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

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

Usage is implied by the mention that the returned article_version is 'to pass to update_article', which hints at the read-modify-write workflow. However, there is no explicit statement of when to call this versus other content-fetching siblings, nor any prerequisite or exclusion guidance.

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 this is a read-only, non-destructive, non-open-world operation, so the safety profile is covered. The description adds useful behavior beyond that: it warns that full reads are expensive, explains token implications of rendering choices, states that omitting `render` renders nothing, and notes that rendering one animation can return `warnings`. However, much of this behavioral detail is duplicated in the nested schema descriptions rather than being uniquely carried by the top-level description.

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

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

The description is front-loaded with a clear purpose and organized into useful sections, but it is very long and repeatedly restates details already present in the input schema, especially for `select`, `render`, and `max_width`. The examples are helpful, but the definition would be stronger if it removed duplicated schema content and kept only the highest-value guidance.

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 burden of explaining return values, and it does so thoroughly: it describes element wrapper fields, type-specific data, keyframes, HTML animation metadata, clip-level fields, `transition`, `voiceover_words`, and render `warnings`. Given the tool's complexity and nested parameters, the definition is complete enough for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the nested `select` and `render` schemas are already highly descriptive, so the baseline is 3. The description does add value through scenario-oriented examples such as using `select` to fix a layout, run a timing pass, or sync visuals to narration, but many of its parameter examples repeat the schema almost verbatim.

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

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

The opening sentence states a specific verb and resource: 'Read one clip' and lists the main returned components (elements, voiceover, background, transition). It also clearly distinguishes the optional render behavior from the JSON read, so an agent can tell what this tool is for without opening the schema.

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

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

The description gives explicit guidance on when to use `select` versus `render`, when to omit `select`, when to use single timestamps versus grids, and when `layout:'separate'` is worth the cost. It also names alternatives and related tools such as `read_animation`, `update_elements`, `edit_animation`, `update_groups`, and `get_project`, reducing the chance of using the wrong sibling.

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 say readOnlyHint=true and destructiveHint=false, but the description discloses real side effects the annotations cannot: every read is logged into the workspace's recents, and use=true mutates the clueprint's use count and apply analytics. It also discloses return encoding (text inline, binary as presigned GET URLs) and the presence of a `brand`/brand_locked flag in the reply.

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 verb, then a clean bulleted enumeration of modes, then logging/usage semantics, then the build guidance — a logical order with no filler. The closing brand-kit-vs-clueprint paragraph is dense and long for a fetch tool, though it directly informs the `use=true` decision, so it earns its place but costs some tightness.

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 five parameters, no output schema, and a mutation-adjacent `use` flag, the description covers the missing ground: return shapes per mode, side effects, re-skin/brand_locked policy, and the handoff to get_design_guide. An agent can call this correctly on the first try without reading anything else.

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%, so the baseline is 3; the description earns above that by expanding what each include value concretely contains ("metadata + the full file tree (path, mime_type, and size per entry)") and by noting file_paths is ignored outside include='files'. The semantics of `use` and `project_id` interplay (once per build, project_id only when the project exists) are also spelled out.

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

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

States a specific verb+resource ("Fetch clueprint data") and immediately enumerates the four retrieval scopes, so an agent knows exactly what shape of data it is asking for. It is clearly a read of one clueprint, distinguishing it from create_clueprint and update_clueprint by scope and intent.

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 each mode ("Call this first when exploring an unfamiliar clueprint", "call include='tree' first if you also need metadata", "use sparingly on large clueprints") and states the when-to-set condition for `use` ("Pass use=true ONCE, when you start building a project from it"). It also routes the agent to get_design_guide for the complementary brand-kit read.

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 mark this as readOnly and non-destructive, and the description adds meaningful behavior beyond that: comments come back nested with replies, resolved threads are hidden by default, and a plain read represents outstanding work. This gives the agent accurate expectations about response shape and filtering behavior with no contradiction.

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?

Every sentence earns its place: the opener defines the tool, the middle sentences give usage context, and the closing sentence clarifies default behavior. It is front-loaded with the core purpose and contains 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, so the description carries the burden of explaining the return shape; it states that threads are nested with replies and that resolved threads are hidden by default. Combined with full parameter documentation and clear annotations, an agent has sufficient context to invoke 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the practical meaning of include_resolved: history versus outstanding work, and by clarifying that omitted clip_id means project-level comments are included. project_id is not further enriched, but the additional context for the other parameters justifies the higher score.

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: "Read the review comments on a project." It also explicitly distinguishes itself from add_comment, naming it as the sibling that posts but never reads. An agent can immediately determine what this tool does and how it differs from nearby 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 gives explicit when-to-use guidance: read before an editing pass, and again after a build if a reviewer has seen it. It also names the alternative action for replying to a thread, add_comment(parent_comment_id=...), and warns against creating a new top-level note.

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 read-only, closed-world, non-destructive, so the safety profile is covered. The description adds genuine behavior beyond that: the size budget with overflow listed by path for a follow-up call, the reply leading with a short 'brand' section, and the instruction to follow the brand kit by default. Missing only return-shape detail, which is minor for a read tool with 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 and informationally dense—nearly every sentence carries a distinct rule—but it reads as an undifferentiated wall with nested quotes and colons, making the path grammar and the brand rules slow to extract. Sub-headers or bullets per topic would preserve the content at half the parse 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?

All seven optional parameters are accounted for (path, skill, topic, select, project_id, brand_kit_id, clueprint_id), including the interaction between clueprint and brand kit (format vs identity, brand_locked). Default behavior with no arguments is stated, and the overflow behavior is disclosed, so an agent can call this correctly with no guesswork.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3. The description earns more by defining the select path grammar that the schema only hints at ('motion.camera', 'x.*' with children, 'stdlib:<words>', plain words searching all three and returning the path that selects them exactly), and by enumerating brand.<section> values. It also states the constraint on logo reuse (match for_background, never recolor), which no schema field conveys.

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

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

The opening sentence names the three resources it serves (the design guide, the HTML animation pages guide, and the Director's skills) and the 'topic'/'select' framing makes the retrieval model concrete. It is clear enough to distinguish from read_animation/edit_animation, which it explicitly pairs rather than replaces. The only weakness is that the title 'Get design guide' undersells the skills/pages/brand scope, so the agent must read past the name.

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 'Ask for everything you need in ONE call' plus worked example, plus per-topic routing ('pages' returns the whole guide for writing/editing; 'skills' lists then read one with skill+path). It also resolves the project_id vs brand_kit_id choice ('for a project on another kit, or a co-branded scene') and when to add clueprint_id. That is when-and-which guidance, not just what.

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 readOnly/non-destructive/non-open-world, so the bar is lower, yet the description adds real behavior: compact is the default, detail:'full' exposes keyframe rules, and format silently flips to 'json' inside run_script. That default-switching nuance is exactly the kind of thing annotations cannot convey.

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

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

Front-loaded with purpose, then the default behavior, then the query/fields variants, then naming conventions. Four paragraphs is on the long side and the format/run_script point is restated twice, but almost every sentence carries an operational fact.

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 conveys the return shape: TypeScript declarations with types, one-line notes and keyframable list by default, full notes/defaults/examples for targeted fields. An agent knows what it will receive and how to narrow it.

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 still adds value by explaining the fields/query interaction (query returns up to 5 matches 'as fields would'), and by documenting camelCase field naming with the snake_case cross-reference that appears nowhere in the schema. The group surface explanation is extra semantics the enum alone doesn't supply.

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 ('Return the schema for an element type's type_data, as TypeScript declarations') and makes the artifact concrete. It is clearly distinguishable from siblings like get_clip or add_elements, which it names as downstream consumers.

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 to call it before add_elements/update_elements when the field shape is unknown, and gives a separate routing rule for element_type='group'. The when-not condition ('when you don't already know the field shape') is stated plainly.

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?

Beyond the readOnlyHint/destructiveHint annotations, it discloses non-obvious behavior: re-publishing replaces the video behind the SAME URL without changing embed code, and while latest_publish is queued/inprogress the embed_url still serves the previous version. These are exactly the traits annotations cannot convey.

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

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

Front-loaded with the core purpose and both return fields, then a compact returns line, then tight bullets enumerating published=false, published=true, and latest_publish states. Every sentence 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?

Although there is no output schema, the description enumerates the return shape (project_id, published, embed_url, embed_code, latest_publish) and explains the state semantics, and the annotations cover the safety profile. An agent has everything needed to call and interpret it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single project_id parameter is already documented in the schema, so the baseline is 3. The description reinforces that project_id scopes the embed lookup but adds no format or syntax detail beyond the schema.

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

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

The description states a specific verb and resource (retrieve a project's embeddable video player) and names the exact return fields embed_url and embed_code. It clearly distinguishes this read operation from siblings like export_project and get_export by describing what each returns.

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 branching guidance: when published=false, call export_project(destination="embed") and stop; when published=true, re-publish after editing. It names the alternative tools (export_project, get_export) and the exact conditions that select 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?

Annotations already declare readOnly/non-destructive/openWorld=false, but the description goes well beyond: it discloses the blocking/long-poll behavior, that the call holds until completion/failure/stall or wait_seconds expires, the full status vocabulary, link expiry (1 hour via expires_at), fresh-link minting on repeat calls, and embed-specific return 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?

Purpose and the call/no-call rule are front-loaded, and the state machine, expiry, and embed details are parceled into distinct sentences. It is long, but the length is justified by genuinely non-obvious blocking and expiry behavior; a little more tightening would make it a 5.

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

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

With no output schema, the description carries the return burden and does so: it names the response object fields and explains download_url, filename, expiry, and the embed_url/embed_code variants. An agent has everything needed to invoke and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: exactly one of export_id or project_id, and that project_id resolves to the most recently REQUESTED export (which may still be in progress) rather than the newest finished one. It also reinforces wait_seconds semantics and the run_script rule.

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: reads a project's video export status and, once done, its link. It distinguishes itself from the write-side sibling by naming export_project as the tool that starts the export and by returning a concrete field set.

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-to-call (user asks for the link or status), when-not (not to wait on an export just started), anti-patterns (don't call in a loop), and the alternative action for the no-export case (call export_project). Routing to and away from siblings is fully specified.

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 say read-only/non-destructive; the description adds the materially important behavior that the call blocks up to wait_seconds, that the job continues to completion regardless of polling, and what the response fields mean. That is exactly the context an agent needs to avoid a polling loop.

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 trigger condition, then return shape, then the non-obvious 'runs to completion whether or not you poll' note. Slight overlap between 'waits for it rather than returning immediately, so one call is usually enough' and the final sentence, but no sentence is wasted.

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

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

No output schema exists, and the description fully compensates by enumerating the return fields, the three status values, and where outputs and errors appear. For a two-parameter blocking read tool, nothing an agent needs in order 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, but the description adds the intent behind wait_seconds ('how long you are willing to hold') and frames it as a tradeoff rather than a raw number. job_id is described only indirectly via the 'returned from the starting tool' framing, which the schema already covers.

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 (fetch the outcome) and resource (a media job) plus concrete examples of what such jobs produce (article GIF, frame grab). Crucially it pins the tool to the exact trigger condition — 'the tool that started it returned { job_id, status: "processing" }' — which separates it from generator siblings like generate_media or add_article_media.

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

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

Gives clear when-to-use context (only after an inline-incomplete start) and tells the agent one call usually suffices, so it should not be looped. It stops short of naming the specific alternative for other job types (e.g. get_script_job for scripts), so the sibling routing is implied rather than explicit.

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

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 still contributes real behavioral context beyond that: the `duration_pending` / `durations_pending` caveat for clips whose voiceover is still rendering, the null semantics for `brand_kit` (`no_kit` case vs workspace-has-none case), and the fact that an over-long render reply names the next `from_cut`/`from_clip` for pagination.

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

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

Purpose and the audio-copy workflow are front-loaded, but the single dense run-on paragraph mixes return-shape documentation, cross-tool routing, pending-duration caveats, brand-kit null semantics, and render modes without structure. Every fact is useful, yet the wall of backticked identifiers makes it harder to scan than it needs to be.

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

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

There is no output schema, so the description carries the return-value burden — and it does, naming every top-level field (`audio_tracks` wire shape, `brand_kit`, `clueprint`, `durations_pending`) and their null conditions. For a two-parameter read tool with nested render options, nothing an agent needs in order 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 earns above baseline by reframing `render` as "check the whole film in ONE image instead of the summary" and summarizing the three mutually exclusive modes (seams, clips, at) plus the per-clip at-position option, which is more than the schema's field-level notes convey.

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+resource ("Get a summary of a project") and immediately enumerates what the summary contains: canvas dimensions, per-clip summary fields, and `audio_tracks`. It also distinguishes itself from `get_clip`, `get_design_guide`, and `add_audio` by naming what each of those covers instead.

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-to-use ("Call this to understand what's in the project before making changes") and explicit alternatives: `get_design_guide({project_id})` for colors/fonts/logos/guidelines, `get_clip` for per-clip timings and filmstrip seams. It also spells out a concrete workflow — read `audio_tracks` here and feed the same fields to `add_audio` on a target project — which is exactly the routing an agent needs.

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, and the description adds substantial context beyond that: it is a snapshot, recordings can take hours, partial results are surfaced via an errors array with null/missing parts while the rest stays accurate. This is genuine behavioral disclosure not present in 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, then output shape, then usage semantics, then the polling caveat. Despite its length, each segment carries unique information an agent needs, and the ordering puts the most decision-relevant content 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?

There is no output schema, so the description carries the full return-value burden and does so thoroughly: it enumerates the usage object, row fields, the kind:'run' case with no project_id, and the errors structure. Nothing an agent needs to interpret results or call 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 goes beyond by spelling out the state semantics shared with the enum param (pending waits for a free slot and self-starts; in_progress/done/failed) and by defining row ordering (in-progress first, then most recent). It doesn't add syntax for limit or project_id, so it lands just above baseline rather than a 5.

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 (status of this workspace's auto-recordings) plus the generations-usage angle, and anchors it concretely to 'the same view as the Recordings page in the Clueso app.' An agent can distinguish it from sibling read tools like get_project or check_uploads without opening the schema.

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

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

Explicit when-to-use guidance: 'check once after record_screen, then again when the user asks,' and an explicit when-not with rationale: 'do not poll in a loop.' This routes the agent correctly relative to the record_screen sibling and sets the snapshot expectation.

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 readOnly and non-destructive, so the bar is lower, yet the description adds genuinely new behavior: the call blocks/waits rather than returning immediately, and the script runs to completion whether or not you poll. It also documents the response shape and status enumeration, which is valuable given 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-loads the triggering condition, then the waiting behavior, then the return shape — a sensible order with no filler. Slightly dense but every sentence carries information an agent needs.

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

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

With no output schema, the description correctly carries the return contract: the fields, the status enum (processing/completed/failed), and what `result` contains. Combined with the waiting semantics, nothing an agent needs to call this 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 100%, so both parameters are already documented in the schema. The description reinforces wait_seconds ('set wait_seconds to how long you are willing to hold'), but adds no syntax or default details beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the outcome of a run_script that did not finish inline') and explicitly scopes it to the async/long-running case, which cleanly separates it from the run_script sibling. An agent can tell immediately when this tool applies.

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

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

Gives clear context: use it for a run_script that did not finish inline, and notes that waiting means 'one call is usually enough,' implicitly discouraging polling loops. It stops short of naming alternatives or explicit when-not conditions, so it falls just under full marks.

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 flag destructiveHint=true, but the description adds non-obvious behavior the annotations cannot: background company research landing "in about a minute", recolor being an "AI redraw ... (about 30 seconds, budgeted per workspace)", the failure path for un-whitenable logos, and exactly what delete does to projects and to the last remaining kit.

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 purpose followed by a clean per-action bullet list; each bullet is scoped by action name, which is the right structure for an eight-action tool. The `update` bullet is a very dense run-on of nested field names that is hard to parse in one pass, but the information is load-bearing 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 10-parameter, nested-object, no-output-schema tool, the description covers the destructive path and its confirmation requirement, permissions, async timing for the two AI operations, the shape of the returned `applied` field, and where kit ids come from. Nothing an agent needs to invoke it safely 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 90%, so most parameters are already documented; the description's real contribution is disambiguating `replace` ("empty means the placeholder sections, so the user's own uploads and edits stay") and `add` ("keeps the kit's items and adds the site's"), which the schema does not. It also expands the opaque `changes` object's nested shape, which the schema leaves as additionalProperties: {}.

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

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

States a specific verb and resource ("Create and change the workspace's brand kits") and enumerates all eight actions so the agent knows the full surface. It also scopes the audience ("editors and admins") and explicitly defers reads to siblings (`find(type='brand_kits')`, `get_design_guide`), separating it from those 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?

Every action carries its own when-to-use context, including the preview-then-apply pairing ("preview_fill: what `url` would give ... Changes nothing" vs "fill: apply it"). It gives explicit preconditions for the risky path: "Ask the user first (saying so for the last kit), and pass `confirmed: true` only after they agree."

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 well beyond the annotations: workspace-wide blast radius, the instruction to inform the user on change, the compile-at-generation-time behavior requiring regeneration, the 'entry_exists' refusal with a `current` field and a confirmation-gated replace flow, and role/plan prerequisites with a refusal that names the cause. This is consistent with destructiveHint=true (remove deletes entries) and readOnlyHint=false, with no contradiction.

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 critical do-not-respell warning, then a tightly organized per-action bullet list. Dense but every sentence carries actionable information; nothing is restated from the schema verbatim.

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 9-parameter, multi-action tool with no output schema, the description still specifies return shapes for list and the error payload for set, plus prerequisites and side effects. An agent has everything needed to select the action, pick spelling vs ipa, and handle refusals.

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 89%, so the baseline is 3, but the description adds real semantics: spelling works on every voice and is preferred, ipa is English ElevenLabs voices only and ignored on clips with [audio tags], language "" means all in list mode, and replace: true is only valid after user confirmation. It also documents result shapes per action.

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 pair and resource ('Read and edit the workspace pronunciation dictionary'), names the settings location, and enumerates the four actions with their return shapes. It is unmistakably distinct from siblings like set_voice or voiceover_batch.

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 ('whenever the user asks how a word, name or acronym is said') and an explicit anti-pattern with the reason ('Do NOT respell the word in the voiceover script'). It also names the required follow-up action (regenerate via voiceover_batch generate_speech) and the alternative route for setting entries.

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, and the description stays consistent while adding real context: code returns as untrusted data that must not be acted on, and each animation is a project-local copy that never pulls newer library versions. The drawback is that roughly half the text documents run_script operations (place, presets, make_live, breaking_unconfirmed) rather than this tool's own behavior, so the transparency gain for read_animation itself is diluted.

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

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

It is front-loaded and bullet-formatted, but the second paragraph is a long run of sibling-tool documentation — place signatures, preset operations, renamedFrom, confirm_breaking — that an agent calling read_animation does not need and that belongs with run_script or edit_animation. That bulk materially inflates the definition without making this tool easier to invoke.

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 telling the agent what comes back, and it does so per mode (element/revision mapping, page parameters and cues, probe verdicts, numbered lines, grep hits with line numbers). Only minor gaps remain, such as pagination or size limits on large sites, which are not addressed.

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 per-parameter meaning is already documented and baseline would be 3. The description earns extra credit by conveying cross-parameter semantics the schema cannot: element_id requires project_id, project_id alone downgrades to a listing, range and format only apply with path, and all:true only makes sense with pattern and no animation.

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

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

The first sentence gives a specific verb and resource ('Read an HTML animation's page site … like a repository') and immediately scopes it as read-only. The four bullets then enumerate the distinct read modes (project listing, element/animation summary, file path, grep), so an agent can tell exactly which payload it will get and distinguish this from edit_animation or find.

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?

Each bullet states the parameter combination that selects a mode, so mode selection is explicit rather than inferred. It also routes heavier or mutating work elsewhere ('Occasional and bulk work lives in run_script'), naming the alternative and the condition that picks 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?

Goes well past the annotations (which only say non-read-only, non-destructive, open-world): discloses that created clips are placeholders that become video on completion so deleting one loses a scene, that article placeholders are auto-inserted into plainDoc, that jobs can take hours, and that credentials and an add-on are prerequisites with a documented degraded path. That is exactly the operational context an agent needs before invoking.

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

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

Front-loads what it does, then side effects, then progress-checking, then prerequisites/fallback — a logical order with little waste. It is dense and slightly long across four blocks, but nearly every sentence carries non-obvious 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 16-parameter, async, job-dispatching tool with no output schema, the description covers prerequisites, side effects, monitoring, and failure fallback. It does not say what identifiers come back from a successful call (only that recording_session_id can be read off get_clip), which is the one remaining 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 the schema already explains all 16 parameters, including the legacy flags and mode enums; the description adds no parameter-level detail of its own beyond mentioning add_clips(kind='video') as an alternative. Baseline 3 applies when the schema carries the semantics.

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 ('Records the product on a mock (Code record) as a screen-recording clip') and spells out the side effects (blank placeholder clips, job entities, AVS dispatch). It is clearly distinct from sibling tools like add_clips or upload_file, which it names as the manual alternative.

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 routes the agent: check progress with get_recording_activity(project_id) and do not poll in a loop; if the workspace lacks the Auto-Recording add-on, fall back to upload_file then add_clips(kind='video') rather than treating it as an error. It also tells the agent how to pick the `target` value from the user's request.

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?

Adds substantial behavior beyond the destructiveHint annotation: link cleanup semantics, end-action jump behavior, index shifting after removal, ordering requirements for multiple removals, and whole-project concurrency constraints. These are exactly the side effects an agent needs before invoking a destructive mutation.

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 front-loaded with the core action and constraint, then proceeds through side effects, index behavior, and concurrency. Despite its length, every sentence carries operational information needed to avoid incorrect destructive 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?

For a destructive two-parameter mutation with no output schema, the description is complete enough: it covers the main constraint, side effects, index behavior, and concurrency serialization. Nothing essential for safe invocation appears to be 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 already 100%, but the description still adds meaningful semantics about clip_index: zero-based removal, post-removal index shifting, and the need to remove highest-to-lowest or re-derive indices between calls. project_id semantics are mostly 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: remove a clip from the project by index. It clearly distinguishes the operation from broader project/element removal tools and includes the key constraint that the last remaining clip cannot be removed.

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 clear usage context, including the important when-not condition that the last remaining clip cannot be removed, plus ordering guidance for multiple removals and explicit serialization requirements. It does not name sibling alternatives, but the operational guidance is otherwise strong.

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 flag destructive=true and readOnly=false, but the description goes well beyond them: each removal is a granular element_remove patch, the whole batch persists in ONE save, and concurrent edits to the same element id are REJECTED rather than last-write-win. What is missing is failure behavior for nonexistent clips/element ids or permission requirements, so it falls 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-loaded with the core verb and resource in the first sentence, then structured into a labeled Concurrency block. Dense but every sentence carries operational information; the parenthetical conflict-domain phrasing is slightly wordy but earns its place.

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

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

For a 4-parameter destructive batch mutation with annotations covering the safety profile and no output schema, the description supplies atomicity, concurrency domain, exclusions, and alternative routing. Remaining gap is error/validation behavior for bad indices or ids, and return shape confirmation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself already documents the two calling conventions (removals array vs clip_index + element_ids) and the {clip_index, element_id} entry shape. The description's restatement of the entry format adds little beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (remove), resource (elements), and scope (many, across one or more clips, in one call). The final sentence explicitly distinguishes it from remove_from_project for audio tracks, so an agent can route correctly 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 when-to-use-this-vs-alternatives routing ('To remove an audio track ... use remove_from_project(target="audio")') plus when-not-to-run-concurrently with named tools (update_clips, structural clip ops, add_audio, update_project). It also says when to fan out across subagents.

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?

Even though destructiveHint=true already signals mutation, the description adds rich behavioral context: grouping children survive by default, keep_children=false deletes the whole subtree, element_ids are removed one at a time with safe retries, and audio removal is a whole-project mutation. This goes far beyond the annotations.

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

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

The description is structured with bullet-like target sections and a concurrency paragraph. It is dense but not bloated; every sentence carries meaningful operational or safety information. The upfront summary is immediately followed by mode-specific details.

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 all three removal modes, required and optional parameters, default behavior, failure semantics, concurrency constraints, and when to prefer a sibling tool. Given there is no output schema, the lack of return-value detail is not a completeness 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 coverage is 100%, so a baseline of 3 applies. The description still adds meaning by clarifying the role of clip_index as an optional hint for element, a requirement for group, and explaining the default behavior of keep_children. It also frames element_ids versus element_id usage clearly, though much is repeated from the schema.

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

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

The description opens with a clear, specific statement: 'Remove an element, a group or an audio track from a project.' It identifies the exact verb, resource types, and scope. It further differentiates from the sibling tool remove_elements by recommending it for large batches.

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 explicit when-to-use guidance per target mode, listing required parameters for each. It also names an alternative tool (remove_elements) for large batches and gives concurrency rules for when parallel use is safe versus serialized.

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?

The description discloses several important behaviors beyond annotations: the rejection of partial lists to prevent silent drops, the z-index rendering rule, grouped-clip behavior, and the specific rejection of orders that split a group with a non-member between its members. This gives an agent accurate expectations for validation and failure modes.

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

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

The description is front-loaded with the essential z-index rule, followed by input requirements and group caveats. Every sentence carries meaningful operational information, and the structure guides the agent from general behavior to specific constraints without wasted words.

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 three required parameters and no output schema, the description is complete: it explains what the tool does, how to source the required list, what order semantics are, and how the handler handles invalid or group-splitting inputs. No critical calling information 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%, and the ordered_element_ids schema already explains position and z-index. The description adds value by requiring the full current list, directing the agent to get_clip for the exact order, and explaining group-related constraints on the order. This is more than the baseline but not a large semantic leap beyond the schema.

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

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

The first sentence uses a specific verb and resource: 'Reorder the elements inside a clip,' and immediately defines the core semantic (list position is z-index, later entries render on top). This clearly distinguishes reorder_elements from siblings like add_elements, remove_elements, and update_elements.

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

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

The description gives explicit usage conditions: callers must pass the full set of element IDs currently in the clip, partial lists are rejected, and get_clip is named as the correct way to obtain the current order. It also names an alternative action, update_elements(group), for removing an element from a group before reordering.

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 say destructiveHint=true and readOnlyHint=false; the description goes far beyond, disclosing that a script is NOT a transaction, that writes_applied counts what landed, that failed tool calls throw, that images are omitted, that sleep exceeding the budget fails the run and holds a concurrency slot, and listing hard limits (1000 calls, 200K code, 50s/15min/30min). It also explains idempotency semantics precisely, including that a failed run's key will not re-execute.

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?

Purpose and the core compute-don't-hand-write principle are front-loaded and headers make it navigable, but the description sprawls well past a thousand words with two separate add_elements code examples and discursive asides ('which is often', 'that also makes a single-call script worthwhile'). Most content earns its place for a tool this complex, but the volume is disproportionate and could be tightened considerably.

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 meta-tool with five params, no output schema, and an unbounded language surface, the description covers execution model, return shape ({ok, calls, writes_applied, result, stdout}), error semantics, image handling, stdlib availability, job handoff, and limits. Nothing an agent needs to invoke it safely 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% and the schema descriptions already define dry_run, wait_seconds, idempotency_key, and timeout_seconds thoroughly, so baseline is 3. The description still adds actionable context, notably the recommendation to set idempotency_key on anything that builds, that a resumed job inherits a longer budget, and which slow tools (analyze_audio transcript/beats, export_project, auto_sync) will burn the timeout budget.

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

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

The opening sentence names the specific action and resource: write a JavaScript program that calls this server's other tools. It immediately separates the tool from every sibling by framing it as an orchestration layer, and the 'CALLING TOOLS' section explains the global-function calling convention that makes it distinct.

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 ('use it whenever code says the thing more directly than a sequence of separate calls'), when-not-to ('never wait on an export in a script', 'call get_clip yourself, outside a script, when YOU need to look at one'), and which siblings to prefer for narrowing reads at the source rather than in-script.

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 well beyond the annotations (which only say non-readOnly, non-destructive) by disclosing failure semantics: an unmatched name silently applies the workspace default and returns `matched: false`, and `engine_substituted: true` means the voice was applied on a different engine. It also explains name lookup (case-insensitive, saved code accepted) and the safe default for `voice_version`.

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 scope, then usage, then failure modes, then the version caveat — a logical order with no filler sentences. It runs a bit long, and the 'Common engines' line partly restates the enum-ish schema examples, but each paragraph still carries actionable behavior.

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 naming the fields an agent must inspect (`matched`, `engine_substituted`, `voiceover.voice.name`/`engine`). Combined with the mutation scope and the recovery procedure, an agent has everything needed to call and interpret this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: lookup is case-insensitive by name, a saved voice's code also works, `voice_engine` is a preference hint rather than a hard constraint, and omitting `clip_ids` means every clip. It also adds the 'leave unset / legacy only on explicit request' rule for `voice_version`.

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+resource and immediately states the two scopes (every clip in a project, or only those in `clip_ids`). This distinguishes it from siblings like `update_audio`, `voiceover_batch`, or `update_clips`, which do not target voice assignment.

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 when to use it (apply a clueprint's voice, or switch all clips in one call) and gives the conditional rule for `clip_ids` when the user names specific clips. It also routes the agent to `find(type='voices')` as the recovery path and warns against guessing a 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?

The description adds substantial behavioral detail beyond the annotations: the left clip keeps the original ID, the right clip gets a new ID and is inserted immediately after, spanning elements are duplicated with adjusted timing, interactive elements are treated as an exception, and voiceover/transcript data is split proportionally. It also discloses the whole-project conflict domain and serialization requirement, which is critical operational context not captured by the annotations.

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

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

The description is front-loaded with the core operation and then presents side effects, exceptions, and concurrency in a logical order. Every sentence contributes useful information, with no filler or redundant restatement of the schema.

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

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

For a project-mutating split operation with no output schema, the description covers the important effects an agent needs: ID handling, insertion order, element duplication and exceptions, transcript splitting, and concurrency constraints. The remaining omissions, such as full response shape or permission requirements, are minor relative to the behavioral detail provided.

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 meaning of project_id, clip_index, and split_time is already fully documented in the schema. The description confirms that splitting occurs at a timestamp but does not add parameter-specific semantics 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 states a specific verb and resource: splitting a video clip into two clips at a timestamp. It also specifies the resulting left and right clips and their ID behavior, which makes the operation unmistakable and distinguishable from siblings such as duplicate_clip or remove_clip.

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 establishes the operation context and gives an important concurrency restriction: serialize the mutation and do not run it in parallel with any other project mutation. It does not explicitly name alternative sibling tools like duplicate_clip or update_clips, so the tool-selection guidance is strong but not fully comparative.

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?

Beyond the annotations, the description discloses the key behavioral trait: the workspace choice persists for the client 'across reconnects' until changed. This is essential context for an agent deciding whether and when to call this stateful tool.

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: the action, the persistence behavior, and the lookup mechanism. All information is front-loaded and every sentence contributes meaning with no redundancy.

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

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

For a single-parameter state-switching tool with no output schema, this description fully covers what an agent needs to know: the action, the persistence semantics, and how to find valid values. There are no significant 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?

The schema already documents workspaceId as 'Workspace ID to switch to' with 100% coverage. The description adds practical value by telling the agent to use find(type='workspaces') to see available options, which clarifies where a valid workspaceId comes from.

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 ('Switch') and a clear resource ('active workspace'), and immediately clarifies the state-changing nature of the operation. It is easily distinguished from all sibling tools, none of which perform workspace switching.

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 explains that this should be used when you want 'every later call' to operate in the new workspace, which is clear contextual guidance. It also points to find(type='workspaces') for discovering options, though it does not list explicit exclusions because no direct alternative exists.

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 well past the destructiveHint/readOnlyHint annotations by disclosing that changes are workspace-wide, apply only to translations made afterward, require re-translation to take effect, and need an editor/admin role plus an Enterprise plan with a refusal that names which requirement failed. It also documents the error contracts (entry_exists with `current`, several_terms) and the required user-confirmation flow before replace: true, which is exactly the risk 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?

Front-loads purpose, then when-to-use with the anti-pattern, then the data model, then a bulleted per-action breakdown, then permissions — a sensible escalation. It is dense rather than padded, though the data-model paragraph and the per-action bullets restate some of the same field semantics, costing some tightness.

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

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

For a 12-parameter destructive mutation tool with no output schema, the description supplies the missing return shape inline (term and rule field lists, term_count, the 200-term cap), plus scope, timing, permission/plan gating and error recovery. An agent can call every action correctly, including the two-step confirmation path, using this text alone.

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 92%, so the schema carries most parameter documentation, but the description still adds real meaning: `original` → `translated` with the note that the source keeps the original as is, `languages` omitting meaning 'every language on a new term, unchanged on a replace', `case_sensitive` defaulting false, and 'ONE rule per language' for set_rule. It adds interpretation and defaults rather than syntax examples, so it sits just above the high-coverage baseline rather than at the top.

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 concrete verb pair (read and edit) against a concrete resource (workspace translation glossary and translation rules), then enumerates the five supported actions. Nothing about this overlaps ambiguously with the sibling set (captions, update_article, pronunciation), so an agent can route to it without opening the schema.

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

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

Gives explicit triggers (user states how a term must be translated, a brand name must stay untranslated, or how a language's tone/formality should read) and an explicit anti-pattern ('Do NOT hand-edit translated captions or text ... the next translation repeats the mistake'). It also points to the follow-up action ('translate' on captions) needed to make changes take effect.

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?

Discloses non-obvious side effects the annotations do not: screenshots dropped from the markdown are deleted, markdown order defines final order, and altered <EMBED> placeholders delete their referents, plus optimistic-concurrency refusal on stale versions. One tension worth noting: annotations say destructiveHint=false while the description describes implicit deletions; and it doesn't say whether non-markdown article content (elements, media) survives an update.

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

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

Front-loaded with the core action, then the placeholder rules, then the workflow — all sentences carry information. It is dense and slightly repetitive with the article_version schema text, but nothing is wasted.

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

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

With no output schema and a mutating tool, the description covers workflow, versioning, and deletion semantics well. The remaining gap is what an update does to article parts not represented in the markdown (elements, existing media outside screenshots/embeds).

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 definitions are already documented, but the description adds real meaning: where article_version comes from and why omitting it loses concurrent edits, plus the SCREENSHOT/EMBED placeholder conventions that govern the markdown string. It stops short of explaining what the id format in placeholders looks like.

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