Clueso

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral context: it captures a frame from the base video or attaches an uploaded image, returns a screenshot_id, and requires a video clip for GIFs. This goes beyond the annotations by explaining the underlying mechanism and precondition.

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 and well-structured with bullet points for each kind. It front-loads the primary purpose, then provides conditional details. Every sentence adds necessary information, with no redundant or filler 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?

Given the tool's moderate complexity (5 parameters, 2 required), the description fully covers all parameter combinations, return value, and prerequisites. It even explains how to integrate the result with update_article. Without an output schema, it compensates by describing the output (screenshot_id) clearly.

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 the schema covers all parameters with descriptions, the tool description adds crucial relational semantics: it explicitly states that for kind='image', timestamp and mcp_upload_id are mutually exclusive and one is required, and for kind='gif', timestamp is the start time and duration is in seconds. This clarifies the dependencies and constraints beyond the flat schema descriptions.

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

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

The description clearly states the tool's function: 'Add a screenshot or GIF to the article.' It specifies the resource (article) and the action (add media), and distinguishes from sibling update_article_media by focusing on adding new media rather than updating existing. The mention of returning a screenshot_id further clarifies its role in the workflow.

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 conditional usage for kind='image' (timestamp OR mcp_upload_id) and kind='gif' (timestamp + duration), with the note that the project must have a video clip for GIFs. It also explains how the returned screenshot_id is used with update_article, giving clear context for when and how to invoke 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?

Beyond the readOnly=false annotation, the description discloses key behavioral traits: the audio is a project-level layer that does not consume a clip slot; guide_end_time defaults to 'end of project' at call time and will NOT auto-extend; Freesound src handles are opaque and resolved server-side; mcp_upload_id resolves to a presigned URL server-side; and the whole-project conflict domain means serialization is required against all other mutations.

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 lengthy but justified by the tool's 14 parameters and two modes. It is front-loaded with the core purpose, uses scannable bullets for music vs sfx, and ends with a critical concurrency/time-capture warning—each sentence earns its place 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?

Given the complexity (14 params, two types, multiple source forms, trimming semantics, and concurrency constraints) and no output schema, the description is remarkably complete. It covers selection, invocation, parameter source, default behavior, edge cases, and concurrency—leaving no major gap for an agent to make a mistake.

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 substantial semantic value: it explains the difference between guide_*_time (timeline placement) and music_*_time (source trimming), clarifies the source of source_duration, details the behavior of opaque Freesound handles, and explains the default-capture behavior of guide_end_time. This goes well beyond the schema property descriptions.

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

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

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.' It clearly distinguishes from the sibling add_clips by stating it does NOT consume a clip slot, and it explicitly points to add_clips(kind='video') as the alternative for inserting an audio file as a sequential 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 provides explicit when-to-use guidance: background music/soundtrack over the timeline, and explicitly names the alternative (add_clips with audio mime_type) for sequential insertion with auto-transcription. It also gives concrete instructions for using find(), analyze_audio, upload_file, and covers legacy sfx_key, plus strong concurrency guidance ('serialize; do not run in parallel').

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 reveals critical behavioral details: the background pipeline for video, 24h cache, N+1 clip behavior for blank clips, and the whole-project mutation conflict domain. It also explains subtle effects like auto_elements only mattering on cache miss and the original audio always retained. No contradiction with annotations; in fact, it enriches them.

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 meticulously structured with line breaks and clear sub-sections for each kind. It front-loads the core purpose and then provides detailed, relevant information without fluff. Every sentence earns its place, covering behavior, parameters, and concurrency in an organized manner.

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 complexity (three modes, multiple parameters, concurrency), the description is remarkably complete. It covers all modes, parameter semantics, concurrency safety, and alternative tools. No output schema exists, so the description doesn't need to explain return values; it provides all necessary context for an agent 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 description coverage is 100%, the description adds substantial semantic meaning beyond the schema: it explains how parameters interact (e.g., 'Without cuts the whole upload becomes one clip'), the N+1 clip behavior, the meaning of voiceover_text ('saved as v2'), and the role of mcp_upload_id in cache hits. It clarifies defaults and edge cases that the schema does not, enhancing the agent's ability to use parameters correctly.

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

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

The description clearly states the tool's function: 'Create new clips on a project' and explicitly distinguishes its three modes (blank, pptx, video). It differentiates from sibling tools by naming alternatives (e.g., add_elements for overlays, add_audio for background music), making its purpose unambiguous. The specific verb 'Create' + resource 'clips' + project scope is present.

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 for each kind and directly references alternatives for different use cases (e.g., 'use add_elements(element_type=video) instead' for overlays, 'use add_audio instead' for background music). It also includes concurrency constraints (serialize with other mutations on same project) and notes on cache behavior, leaving little ambiguity about when to invoke 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?

Annotations already indicate this is a non-read-only, non-destructive operation. The description adds valuable context beyond annotations by disclosing that comments are attributed to 'Clueso AI' and that they can be project-level or clip-pinned with optional timestamps. It does not contradict 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 two concise sentences. The first names the core action and attribution; the second provides usage modes. No redundant phrases or filler, and the most important information is front-loaded.

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

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

For a simple comment-posting tool with 4 parameters, the description fully covers purpose, usage modes, and parameter relationships. The schema documents each parameter, annotations cover safety, and no output schema is needed for a create operation. The description is complete without being verbose.

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 input schema already covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds relational meaning by explaining that 'project level (no clip_id)' vs 'pinned to a specific clip' and that clip_timestamp is 'only used when clip_id is provided,' which clarifies how the parameters interact beyond individual schema descriptions.

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

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

The description states exactly what the tool does: 'Post a review comment on a project, attributed to Clueso AI.' It specifies the verb, resource, and even attribution. It distinguishes itself from sibling add_* tools by focusing on comments, and no other sibling tool handles comments, so there is no confusion.

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

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

The description explicitly says when to use it: 'Use this to leave feedback, suggestions, or notes.' It also clarifies the two placement modes—project-level (no clip_id) or pinned to a clip with an optional timestamp. While it doesn't name alternatives, there are no competing comment tools among siblings, so this is effectively complete 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 ordering, per-item partial success, per-element locking with last-write-wins, z-order implications of grouping, and detailed element-type quirks. This goes far beyond what the annotations convey.

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

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

The description is long but appropriately sized for the tool's complexity, and each section (Reuse, Grouping, Concurrency, Element-type quirks, Animation, Position origin) is clearly labeled and earns its place. The main purpose is front-loaded in the first two sentences.

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

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

For a complex tool with no output schema, the description thoroughly covers prerequisites, concurrency constraints, return behavior (one entry per item, partial success), and per-type exceptions. The only minor gap is a precise return-object shape, though the description already promises 'every new element_id plus its parameter_schema' for component insertion.

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 the schema already has 100% parameter descriptions, the description adds critical semantic details: keyframes must be a sibling of x/y/type_data (not inside type_data), clip_id is accepted but unused, position origins differ for text, and type_data shape must be confirmed via get_element_schema. This is meaningful value 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 opens with the exact action, 'Add many elements across one or more clips in a single tool call,' and explicitly contrasts this with the per-element tool. The verb+resource is specific and distinct from sibling tools like add_audio or add_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?

It provides explicit when-to-use and when-not-to-use guidance: call get_element_schema first, prefer component_id for reuse over rebuilding, use base_component_id only for new variants, and avoid concurrent whole-clip mutations. It even names specific sibling tools to avoid, such as update_clips, add_clips, split_clip, and add_audio.

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 well beyond the annotations by detailing the matching algorithm (case-insensitive, punctuation-stripped, first-match behavior, occurrence indexing), timestamp inverse-mapping when generated_timestamps exist, and the word_not_found error format. This is rich, non-obvious behavioral context.

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

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

The description is well-structured with descriptive headers and bullet lists. Every section earns its place: when to use, matching mechanics, and constraints. It is detailed but not bloated, and front-loads the core action.

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 most necessary context for a complex tool with 7 parameters, including constraints and error behavior. Minor gaps: it doesn't state what a successful response returns (no output schema exists), and the phrase 'Required when the word repeats' slightly conflicts with the schema's default of 1 for occurrence. Overall very strong.

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?

Even though schema coverage is 100%, the description adds meaning beyond the schema: it clarifies how occurrence selects repeated words, how timestamp_seconds maps between clip-relative and original-recording time, and how clip_id/clip_index interact. These are critical semantics not evident from 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 'Insert one sync marker on a clip's transcript', which is a specific verb + resource statement. It clearly distinguishes this from sibling tools like auto_sync by positioning it as a manual insertion tool, not an automatic process.

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 'Use this when' section explicitly lists two scenarios and references auto_sync as the alternative. It also states strong constraints (video clip with source recording, transcript must already contain the word), giving agents clear go/no-go criteria.

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 annotations (readOnlyHint=true), the description discloses behavioral nuances: transcript routes to a music-aware provider, features.has_speech may be false on pure music, beats returns empty for non-music, and features is a cheap dispatcher. This adds context about what results to expect.

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 a mode list and clear sentences, avoiding fluff. Each sentence provides actionable guidance or behavioral notes.

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 params, nested options, and no output schema, the description covers mode behavior, source handling, time range, edge cases, and even output shapes—adequate for an agent to select and call the tool correctly.

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

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

While schema covers all 7 parameters (100% coverage), the description adds rich semantics: mode values are explained with expected outputs, source parameters are clarified with requirements, and range parameters are described as cropping the analysis window. It also names exact output structures like words[{w,start_ms,end_ms}].

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 'Analyze an audio file' and enumerates four distinct modes (transcript, silences, beats, features), each with a specific purpose. It clearly differentiates itself from siblings like add_audio by focusing on analysis rather than adding/modifying audio.

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?

For each mode it states concrete use cases ('Use to get words...', 'Use for auto-trim...', 'Use to align animations...', 'Cheap dispatcher...'). It also advises the source selection ('provide exactly one of mcp_upload_id or file_url') with examples.

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 annotations (which only provide hints), the description discloses critical behavior: async execution with immediate status enum, delayed insertion of sync-marker nodes, platform-wide concurrency cap of 3, and the meaning of status='success' (accepted, not finished). This adds substantial value over the annotation flags.

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 into four focused paragraphs, each covering a distinct aspect (function, async behavior, capacity, rationale). It is front-loaded with the primary action and avoids redundancy, though slightly verbose in places.

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, it thoroughly explains the async nature, how to verify results (poll get_clip), capacity limits, and the service's role in TTS. It even references additional docs. This is comprehensive given the tool's complexity.

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

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

Schema coverage is 100% with both parameters described, but the description adds meaning: clip_id must refer to a clip with a source recording, and the result affects the clip's transcript. This contextualizes the parameters beyond their schema descriptions.

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

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

The description clearly states the verb ('Run the agentic auto-sync pipeline'), resource ('clip with a source recording'), and outcome ('inserts sync-marker nodes into the clip's transcript'). It distinguishes from sibling 'add_sync_point' by emphasizing automatic detection of natural sync points rather than manual addition.

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

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

It gives clear context: requires a source recording, explains that sync points are needed for voiceover TTS, and suggests polling get_clip for verification. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a full 5.

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. The description adds valuable context beyond that: the token covers all files (no per-file calls), returns one mcp_upload_id per file, and should be called once. This is useful behavioral information not covered by 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 three concise sentences, front-loaded with the core action. No redundancy or irrelevant details. Every sentence contributes to understanding the tool's purpose, timing, and follow-up.

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

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

For a simple one-parameter read-only tool, the description covers the action, timing, token scope, and downstream usage. It doesn't detail exact response formatting or error cases, but these are not critical for basic invocation. Given the absence of an output schema, the description provides enough context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining that the token covers all files, which implies a single call returns multiple IDs. This supplements the schema's definition with usage context.

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 ('Fetch') and identifies the resource ('files the user uploaded via the hosted upload page'). It also mentions the return of mcp_upload_id, which differentiates it from upload_file and other sibling tools. This clearly establishes what the tool does.

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

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

The description explicitly states when to call it ('once after the user confirms they are done uploading') and mentions passing IDs to appropriate tools. However, it lacks explicit 'when not to use' or direct alternatives, so it doesn't fully earn a 5.

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 indicate the tool is not read-only and not destructive. The description adds behavioral context by explaining that source_guide_ids trigger automatic clip-by-clip extraction and that the tool creates a structured file directory, which goes beyond the annotation information.

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 primary purpose, uses clear enumeration for folder categories, and includes a conditional for source_guide_ids. Each sentence contributes useful information without unnecessary verbosity.

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 moderate complexity and absence of an output schema, the description fully covers the tool's purpose, structure, optional behavior, and points to additional system instructions. It is sufficiently complete for an agent to select and 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?

Schema description coverage is 100%, so all parameters are already described. The description adds value by clarifying the behavior of source_guide_ids (automatic extraction) and the folder categories that relate to the created structure, supplementing the schema without being redundant.

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 explicitly states the tool 'Create a new clueprint (reusable video template)', using a specific verb and resource. It defines the concept and distinguishes from siblings like get_clueprint and update_clueprint, while also differentiating from create_project by emphasizing reusability.

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

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

The description provides clear context for when to use the tool (creating a reusable video template) and explains the folder structure, even pointing to system instructions. However, it does not explicitly name alternatives or state when not to use it, so it misses the 'explicit when/when-not' level.

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 indicate this is a write operation (readOnlyHint=false, destructiveHint=false). The description adds valuable context: the project starts with one blank clip at index 0 with a default short duration, and it returns an initialClipId. This goes beyond the annotations by explaining the created object's initial state, which is important for follow-up operations.

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 and front-loaded with the core action. The first sentence states the main purpose and return values. The second sentence provides a high-value workflow chain with sibling tool names. The final sentence covers optional parameters. Every sentence adds distinct information without waste.

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, the description explains the return values (projectId and initialClipId) and the initial project state. It also covers optional folder nesting and description setting. Given the tool's relatively low complexity, the description covers all essential context for selecting and invoking the tool, and even provides next-step guidance.

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 with clear descriptions, so the baseline is 3. The description adds minor semantic value by explaining folder placement (root vs nested) and that description is optional, but this is largely redundant with the schema. No parameters need extra explanation 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 opens with a specific verb and resource: 'Create a new blank Clueso project.' It clearly distinguishes from sibling tools by noting it creates a blank project with an initial clip, and explicitly differentiates from tools like create_clueprint. The return values (projectId and initialClipId) further clarify the purpose.

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

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

The description provides explicit workflow guidance: after creating, use update_clips, add_clips, add_elements, and add_audio to continue building. It also directs users to use find(type='folders') to discover folder IDs and explains when to omit folder_id (workspace root). This is strong 'when to use vs alternatives' 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 only indicate it's not read-only and not destructive. The description goes far beyond by disclosing S3 asset re-hosting, independence from the source project, insertion behavior, return value, and the conflict domain (entire target project). This directly contradicts nothing in the annotations and adds essential behavioral context.

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

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

The description is longer than typical but well-structured with clear sections. It is front-loaded with the core action and then provides necessary details. Every sentence earns its place, and the use of bold and line breaks aids readability.

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

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

The tool is a complex mutation with cross-project asset handling and concurrency constraints, and the description fully covers behavior, return value, and serialization requirements. Despite the lack of an output schema, the description mentions the return value and all key edge cases, making it highly 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?

The schema already describes all 4 parameters at 100% coverage. The description adds semantic value by explaining how omitting source_project_id enables same-project mode, how after_clip_id controls insertion, and the cross-project asset implications. This clarifies the relationships between parameters, which the schema alone does not 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?

The description clearly states the tool clones a clip into a target project, with explicit same-project and cross-project modes. This distinguishes it from siblings like duplicate_project (project-level) and add_clips (adding new clips). The verb+resource+scope is specific and actionable.

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 usage patterns for same-project (omit source_project_id) and cross-project, plus insertion semantics via after_clip_id. It also includes a strong concurrency warning ('do not run in parallel with any other mutation'). It does not name alternative tools explicitly, but the context is sufficient for selection.

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 significantly augments the minimal annotations (which only indicate non-read-only, non-destructive) with key behavioral details: the duplicate has its own S3 namespace so source changes never affect it, title and folder default behaviors, what the return value contains, and concurrency implications. This is exactly the kind of context an agent needs that is not available in 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?

The description is detailed but every sentence earns its place: the core purpose, namespace isolation, default rules, return value, and concurrency note are all essential. The bulleted 'Defaults' section is easy to scan, and the concurrency warning is clearly separated. No fluff or repetition.

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

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

With no output schema, the description compensates by stating 'Returns the new project's id and title' and covers concurrency, isolation, and default behaviors. For a tool of this complexity (whole-project duplication with multiple default interactions), the description is complete enough for an agent to invoke it correctly without guessing. It might not cover every error edge case, but it covers the key operational aspects.

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 the schema has 100% parameter coverage, the description adds critical conditional logic: the new_title default changes depending on folder_id being empty/non-empty, and folder_id omission behavior is clarified. This creates a decision rule that the schema alone does not convey, so the description provides substantial meaning beyond the structured fields.

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 'Clone an entire project — every clip, voiceover, asset, and metadata field — into a fresh project,' clearly stating the verb and resource scope. This distinguishes it from sibling duplicate_clip, which targets a single clip, and from create_project, which starts from scratch. The scope is explicit and unambiguous.

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

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

The description gives clear context for when to use it: to duplicate an entire project while preserving all components, and it provides explicit concurrency guidance ('serialize against other mutations on the same source_project_id; do not run them in parallel'). However, it does not explicitly state when not to use it or name alternatives, so it misses the top bar for 5.

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 and destructiveHint, so the description adds extra context: the assumed reading speed (~150 words/minute) and the guarantee of ordering ('Returns durations in the same order'). This goes beyond the structured fields, though it omits potential edge-case behaviors.

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

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

The description is two sentences, front-loaded with the main purpose, and every clause adds value (rate, array requirement, ordering, integration with add_clips). No 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?

Given the tool's simplicity (one parameter), the description covers the input format, the processing assumption, and the output ordering. It doesn't specify units (e.g., seconds), but this is likely implied or documented elsewhere. The lack of an output schema is partially compensated by the explicit mention of ordering.

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 describes the single parameter 'texts' with 100% coverage ('one string per clip'). The description repeats this and adds that durations return in the same order, which is more about output semantics than parameter meaning. Overall, the description adds little 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 clearly states a specific action ('Estimate voiceover duration') and a resource ('one or many clips'), distinguishing it from sibling tools that add or modify clips. It also references the add_clips tool, indicating its role in a workflow.

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

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

It provides clear context on when to use it: pass an array of voiceover texts to get durations, and notes the results are 'ready for add_clips'. While it doesn't explicitly mention when not to use it or list alternatives, the tool is simple enough that this guidance suffices.

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 annotations already indicate this is not read-only and not destructive. The description adds beyond annotations by disclosing the asynchronous behavior (returns immediately, pipeline runs in background) and where the output appears (Exports tab). It also mentions defaults, which is useful context. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the main action and key behavioral outcome. Every sentence contributes essential information: what it does, the async return, and defaults/guidance. No filler or redundant structure.

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 moderate complexity and lack of output schema, the description covers essential context: async execution, return value (export_id), user-facing outcome (Exports tab), and default settings. It omits error handling or status-checking details, but those are beyond the scope of initiating an export. The description is sufficiently complete for an agent to invoke 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?

The input schema already covers all parameters with descriptions and default values for fps, captions, and resolution (100% coverage). The description repeats those defaults and adds 'English' (not a parameter), providing minimal extra meaning. The phrase 'Pass overrides only when needed' reinforces optionality but does not significantly compensate beyond 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 clearly states the verb ('Kick off a video export'), the resource ('project'), and the immediate outcome (returns export_id). It distinguishes the tool from siblings by describing the async background pipeline, which is unique among the listed 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 implies when to use the tool ('to export a project') and gives usage guidance by listing defaults and advising 'Pass overrides only when needed.' It does not explicitly name alternatives, but no sibling tool handles exports, so no exclusion is necessary.

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 many behavioral traits not captured by annotations: Freesound src is an opaque handle, stock video results include safe_src and video_files tiers, freesound audio includes preview_url, clueprint lists are sliced without a marker, duration is in seconds, and stock results are a fixed shortlist. Annotation readOnlyHint/openWorldHint are consistent and expanded with operational details.

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 well-structured with clear sections (type, filters, return) and bullet lists. Every section earns its place given the 19 parameters and numerous edge cases. It is not as tight as a two-sentence description, but the density of necessary detail justifies the length. Minus one because it could be slightly reorganized to reduce inline parenthetical density.

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

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

Despite no output schema, the description fully covers return format ({ type, count, items }), how to feed returned ids into consuming tools, pagination caveats, and special-case behaviors (e.g., component param_keys, safe_src, duration). For a tool with this many parameters and cross-parameter interactions, it is remarkably 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?

Even with 100% schema coverage, the description adds substantial semantic value beyond the schema. For example, it explains that 'query' behaves differently per resource type (semantic search for clueso stock and clueprints, substring otherwise), how provider interacts with image_type/video_type, and that source='all' appends stock only when a query is given. This is meaningfully more than the schema's per-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: 'Find any resource in Clueso by type, optionally filtered by name or exact id.' It clearly states this is the one tool for listing and searching across the workspace, which distinguishes it from sibling tools that are all mutating or action-oriented (add, update, remove, set_voice, etc.).

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

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

Provides explicit guidance on when to use which options and how to choose between providers (e.g., 'clueso' default for music — try this FIRST; 'freesound' for niche tracks). Also explains non-obvious usage such as 'stock media ignores these (fixed shortlist)' and that element_components are workspace-only. This goes far beyond a simple when-to-use statement.

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 sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical asynchronous behavior: immediate element creation, background rendering, polling get_clip with a phantom flag. It also reveals side effects like voiceover_text triggering speech generation. No contradictions with annotations.

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

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

The description is well-structured with a bolded lead sentence, bullet lists for the two kinds, and a concise tip section. Every sentence earns its place, and the layout makes complex information easily skimmable. 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?

Despite having no output schema, the description tells the user exactly what to expect (stable element_id, background render, phantom flag) and how to verify completion. It covers both variants, prerequisites (style_id from find, base_component_id from find), and side effects, making it fully actionable for a complex 15-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic grouping (image-only vs animation-only params, mutual exclusivity of reference_image_url and mcp_upload_id) and practical guidance like the prompt specificity warning for animations. This adds value beyond the already-rich 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 verb+resource: 'Generate an AI image or canvas-code-based animation directly into a clip.' It accurately captures both modes and explicitly contrasts with add_elements for uploaded media, distinguishing it from siblings.

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

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

The tip section gives explicit when-to-use guidance ('whenever the user asks for a generated, AI, or create me a visual') and when-not-to-use ('For uploaded photos / logos / icons / GIFs, use add_elements'). It also clarifies the image vs animation split, which is essential for correct selection.

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 tool is known to be safe. The description adds useful behavioral context about placeholder formatting and return values, which is beyond what annotations 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 concise sentences, all informative and free of redundancy. Every sentence adds value, with the key information front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully explains what the caller will receive (markdown text and screenshot IDs). No critical details are missing.

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

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

Schema description coverage is 100%, so the schema fully documents the single parameter (project_id). The description does not add extra parameter-level details, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and resource ('article content as markdown'), clearly distinguishing it from sibling tools like get_project or get_clip. It also states the output format, making the purpose unambiguous.

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

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

The description clearly implies when to use the tool (when needing article content as markdown), but it does not explicitly mention alternatives or when not to use it. Context is clear, but lacks explicit exclusions.

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 annotation, the description discloses major behavioral traits: response size and context cost, independence of `select` and `render`, the render timestamp default and t=0 entry-animation pitfall, `save` uploading to S3, and the keyframe shape being round-trippable. These details go far beyond what annotations cover.

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?

Despite being long, the description is front-loaded (purpose in first sentence) and organized into clear subsections with examples. Every sentence contributes: usage warnings, parameter interactions, and response shape. There is no redundancy or filler.

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

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

With no output schema, the description thoroughly explains response contents: element wrapper fields, type-specific data, keyframes, transition, voiceover_words, and render output (PNG, presigned_url). It also covers edge cases like null when no transcription and how to get the smallest read. For the tool's complexity, the description is 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?

Although schema descriptions cover all parameters at 100%, the description adds meaningful multi-parameter semantics: interaction of `select` and `render`, `element_ids` as independent row filtering, examples of select combinations, and the meaning of `render: {}` vs `render: { save: true }`. This is very helpful guidance 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 'Read one clip' and enumerates exact contents (elements, voiceover, background, transition) plus optional render for a PNG. This is a specific verb+resource and clearly distinguishes it from sibling tools like get_project or get_element_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 provides extensive usage guidance: 'ASK FOR WHAT YOU NEED' explains how to use `select` for concrete use cases (fix layout, timing pass, sync narration), warns that repeated full reads drain context, and shows how to combine `select`, `render`, and `element_ids` for lean reads. It also mentions round-tripping with update_elements, giving clear when-to-use context.

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=true, destructiveHint=false), the description discloses an important side effect: 'Calling this also logs the clueprint as "used" (fire-and-forget)...' and explains binary files are returned as presigned GET URLs. This adds useful behavioral context without contradicting the primary read-only nature, though the side effect is a subtle deviation from pure read-only semantics.

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

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

The description is well-structured with a clear opening sentence and bullet-pointed include modes. Each line provides essential information without fluff, and the final sentence about the usage log is a single purposeful addition. The length is appropriate for the tool's complexity.

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 explaining return values, and it does so thoroughly. It covers metadata fields, tree structure (path, mime_type, size), file content handling (text inline, binary as presigned URLs), and the default behavior. It also includes guidance on usage weight. The tool is fully understandable without needing additional context.

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. The description adds meaningful semantics to the include parameter by explaining exactly what each enum value returns (metadata, tree, files, all), and clarifies file_paths behavior with examples and the note that it is ignored for other modes. This goes beyond the schema's enum list.

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 'Fetch clueprint data' and then details the specific include modes, clearly defining the tool's scope as retrieving a clueprint's metadata, tree, files, or all. It is distinct from siblings like get_project or get_article by focusing on the clueprint resource, and the verb 'fetch' is 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?

The description gives clear contextual guidance: 'Call this first when exploring an unfamiliar clueprint' for tree mode, and 'use sparingly on large clueprints' for all mode. It also explains when to use files mode and that no follow-up use_clueprint call is needed. However, it does not explicitly list alternative tools or exclusions for 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds context that this is a reference guide with specific content areas, implying a no-side-effect read operation. It does not contradict annotations, and the extra behavioral context is adequate for a static resource.

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

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

Two sentences deliver high-density information: what the guide contains, when to use it, and what it is not. No filler or repetition, front-loaded with the core purpose.

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

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

For a parameterless, read-only tool with no output schema, the description fully covers its purpose, content, and usage context. Sibling differentiation is implicit since no other guide-like tool exists, and the description is self-sufficient.

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

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

The tool has zero parameters, so the description is not required to elaborate on any. With 0 params, the baseline is 4, and the description appropriately focuses on the resource itself rather than parameter syntax.

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

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

The description clearly states the tool provides 'Clueso's house style for composing video clips' with specific topics like concept, typography, color, composition, motion, and pacing. It distinguishes itself from all sibling tools by being the only guide/resource tool, and the verb 'read' is implied, giving a specific action.

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

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

Explicit when-to-use guidance is provided: 'Read it before composing or editing a clip's visuals when you're NOT following a clueprint, or to fill gaps a clueprint leaves silent.' It also clarifies that it is general craft, not clueprint-specific, which helps avoid misuse.

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, covering the safety profile. The description adds contextual behavior beyond annotations by specifying the timing relative to add/update operations and the purpose of retrieving type_data schemas. This adds value without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and the second sentence provides actionable guidance. Every word earns its place 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 simple read-only tool with a clear output (JSON schema) and no output schema, the description is complete. It tells the agent exactly what the tool returns and when to invoke it, and the sibling context makes the guidance even more relevant.

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%—both parameters (element_type and mode) have descriptive comments in the schema. The description itself does not add additional parameter detail beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool returns the JSON schema for an element type's type_data, using a specific verb and resource. It also distinguishes itself from sibling tools by explicitly referencing add_elements/update_elements as the intended usage context.

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

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

The description explicitly instructs when to use this tool: before add_elements or update_elements when the field shape is unknown. This provides clear usage context and names the relevant alternatives, satisfying the highest bar for this dimension.

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 aligns without contradicting. It adds behavioral context by specifying that audio_tracks are flattened to the same wire shape add_audio accepts, revealing the return format and interoperability behavior beyond simple safety hints.

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 three sentences, each serving a distinct purpose: what it returns, how to use the output with add_audio, and when to call it. It's front-loaded with the summary contents and avoids fluff.

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

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

For a read-only getter with one parameter and no output schema, the description covers the essential return contents (canvas dimensions, per-clip summary, audio_tracks) and even provides a cross-tool workflow. It is sufficiently complete for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100% with a single self-explanatory project_id parameter. The description doesn't add parameter-specific semantics, but the baseline of 3 from comprehensive schema coverage applies.

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

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

The description uses a specific verb 'Get' with resource 'project' and enumerates the summary contents (canvas dimensions, per-clip summary, audio_tracks). It distinguishes itself from siblings like get_clip by focusing on the whole project and explicitly positioning itself as a pre-change inspection tool.

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

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

The description explicitly says 'Call this to understand what's in the project before making changes,' providing a clear when-to-use. It also names an alternative workflow: reading audio_tracks and feeding them to add_audio for copying, which shows integration with sibling tools.

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, openWorldHint=true), the description discloses that blank clips are placeholders that become video clips, removing them loses scenes, and article placeholders are auto-inserted into plainDoc. It also notes the prerequisite add-on and credentials. This adds meaningful behavioral context without contradicting annotations.

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

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

The description is three tight paragraphs: main action, behavioral caveats, and prerequisites/fallback. Every sentence provides essential information without fluff. It is front-loaded with the core purpose and remains efficient given the tool's complexity.

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 9 parameters, 4 required, no output schema, and significant side effects, the description covers mechanism, side effects, prerequisites, and fallback. The only minor gap is that it does not specify the return value or success response, but the description already explains the job is sent to AVS, which implies asynchronous processing. This is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not add parameter-level meaning beyond what the schema already provides, but it does set context (e.g., placeholder semantics) that indirectly helps understand scenes. No explicit parameter info in the description, so a 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 opens with a specific verb and resource: 'Create a screen-recording clip in a project.' It then details the mechanism (creates blank placeholder clips, registers job entities, sends to AVS), clearly distinguishing it from siblings like add_clips and upload_file by explaining it's the screen-recording path. It even contrasts with the manual fallback, reinforcing differentiation.

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

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

Explicit guidance is given: requires the Auto-Recording add-on and credentials, and if the workspace lacks them, the manual path (upload_file, then add_clips(kind='video')) is the alternative. This tells the agent both when to use this tool and when to use alternatives, with no ambiguity.

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 destructiveHint annotation, the description discloses important behaviors: index shifting after removal, edge case of last clip, and detailed concurrency conflict domain. This adds significant context beyond the structured 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 compact, front-loaded with the main purpose, then covers constraints and concurrency. Every sentence provides useful information without waste.

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

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

For a destructive mutation with concurrency implications, the description covers the essential edge cases, index behavior, and serialization guidance. It is complete for an agent to select and invoke the tool correctly, even 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 coverage is 100% with clear parameter descriptions. The description largely repeats the meaning of clip_index in behavioral terms (shift down) but does not add new syntax or format details. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the verb ('Remove') and resource ('a clip from the project') and specifies the method ('by index'). It also highlights a key constraint (cannot remove last clip), which distinguishes it from other mutation tools.

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

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

The description provides clear context on how to use this tool (e.g., remove from highest index to lowest for multiple removals) and concurrency constraints. It does not explicitly compare to sibling tools like remove_elements, but the usage context is 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 only indicate destructiveHint=true, but the description adds substantial behavioral context: each removal is a granular element_remove patch under a per-guide lock, the whole batch lands in one save, parallel safety for different elements, serialization for same element IDs, and explicit exclusions for concurrent operations. This goes well beyond the annotation.

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

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

The description is well-structured: first sentence states the core purpose, then a concurrency paragraph with actionable guidance. Every sentence adds value, no fluff. It is moderately long but justified by the complex concurrency 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?

For a destructive batch operation with concurrency implications and no output schema, the description covers purpose, usage, conflict domain, exclusions, and alternatives. It is sufficiently complete for an agent to invoke correctly without additional context.

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

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

Schema description coverage is 100%, with both parameters well-described. The description adds minimal extra param detail—it only restates the entry structure as '{clip_index, element_id}', which mirrors the schema. Since the schema fully explains the parameters, the baseline of 3 is appropriate.

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

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

The description clearly states the operation: 'Remove many elements across one or more clips in a single tool call.' It specifies the resource (elements within clips) and the scope (batch across clips). It also distinguishes from sibling tools by explicitly pointing to remove_from_project for audio tracks and referencing add_elements/update_elements for related operations.

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

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

The description gives explicit when-to-use guidance: it is for batch element removal, explains the conflict domain, and advises against concurrent use with whole-clip/project mutations. It also names the alternative tool for audio tracks ('use remove_from_project(target="audio")'), making the choice clear.

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 destructiveHint=true, and the description adds significant behavioral context: element removal is element-scoped and parallel-safe with other element edits, while audio removal is a whole-project mutation requiring serialization. This goes beyond the annotation and provides important concurrency semantics for safe invocation.

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 for target modes, but the concurrency paragraph is somewhat dense and could be more concise. Still, every sentence serves a purpose and the critical information is front-loaded.

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

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

Given the tool's complexity (two modes, conditional parameters, concurrency constraints) and the absence of an output schema, the description covers all necessary aspects: mode-specific requirements, parameter provenance, and concurrency rules. It is sufficiently detailed for an agent to invoke correctly in various contexts.

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 describes all parameters with conditional notes (e.g., music_id 'required for target=audio') and 100% coverage. The description adds value by grouping parameters by target and noting that music_id is returned by add_audio, providing provenance not present in the schema.

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

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

The description clearly states it removes an element or audio track from a project, and enumerates two distinct target modes with specific resource types. This distinguishes it from sibling tools like remove_clip (removes a clip) and remove_elements (likely removes elements in batch), even if not explicitly contrasted.

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

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

It explicitly specifies when to use each target mode ('target=element' requires clip_index + element_id; 'target=audio' requires music_id), giving clear context for internal selection. However, it does not explicitly mention alternatives like remove_clip or remove_elements for other removal scenarios, so sibling differentiation is incomplete.

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 important behavioral details beyond the annotations: the handler rejects partial lists to prevent silent drops, and explains the z-index ordering semantics. This matches the non-read-only, non-destructive nature while giving context not captured in annotations.

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

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

Two concise, front-loaded paragraphs. The first states the purpose with a clear rule, the second states a critical constraint and provides a pointer to get_clip. Every sentence earns its place with no waste.

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 reorder operation with a critical constraint, it fully explains the z-index semantics, the full-set requirement, and how to get the current list. No output schema is needed, and the description covers all necessary context for an agent 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?

Schema coverage is 100%, so the description need not repeat parameter details. It reinforces the 'full set' requirement and z-index meaning already present in the schema, but adds little new parameter-specific information beyond the prerequisite to use get_clip.

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 exactly what the tool does: 'Reorder the elements inside a clip.' It uses a specific verb and resource, and clarifies the z-index semantics (later entries render on top), distinguishing it from sibling tools that add, remove, or 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?

It provides clear context by requiring the full set of element IDs and pointing to get_clip for retrieving the current list. However, it does not explicitly name alternative tools or specify when not to use it, which would elevate it to a 5.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds value beyond these by noting the bulk behavior, case-insensitive name lookup, and common engine examples, providing practical behavioral context without contradicting annotations.

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

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

The description is concise with three focused paragraphs: core purpose, usage scenarios, and engine examples. No filler or repetition, and the most important information is front-loaded.

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

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

For a simple setter tool with three well-described parameters and clear annotations, the description adequately covers purpose, usage context, and behavioral details. It does not explain return values or error handling, but these are not essential given the tool's simplicity and lack of 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% with descriptions for all three parameters. The description enhances this by clarifying the lookup combination (name + engine), the case-insensitivity rule, and providing common engine values, going beyond the schema's basic field definitions.

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

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

The description opens with a specific action and scope: 'Set the voiceover voice for every clip in a project.' This clearly states the verb, resource, and breadth of effect, distinguishing it from per-clip or batch tools by emphasizing the project-wide application.

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 describes two use cases: applying a clueprint's voice (with direct field references) and switching all clips to a specific voice in one call. However, it does not mention alternatives or when not to use this tool, so it lacks explicit exclusions.

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 indicate readOnly=false and destructive=false. The description goes beyond by detailing concrete effects: left clip keeps ID, right clip gets new ID, spanning elements are duplicated, and voiceover split proportionally. It also discloses the whole-project conflict domain, providing operational transparency.

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 core statement, followed by a concise concurrency note. Every sentence contributes essential behavioral or operational detail; no filler or repetition.

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

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

The description covers the split behavior, element handling, and concurrency constraints thoroughly for a mutation tool. It does not specify return values, but there is no output schema, and the provided detail is otherwise comprehensive. Minor gap: no mention of prerequisites like clip existence or project access.

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 no new parameter-specific meaning beyond what the schema provides (e.g., split_time constraints are already in the schema). It only describes outcomes of parameters, not their 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?

The description states a specific verb and resource: 'Split a video clip into two clips at the given timestamp.' It also clarifies key behavior (ID retention, insertion order, element duplication), distinguishing it from sibling tools like 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 concurrency note provides explicit 'when-not' guidance: do not run with any other mutation on the same project_id. However, it does not mention alternatives (e.g., when to use duplicate_clip instead) or outline conditions for selecting this tool over others.

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=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds the session-scoping context but doesn't explain any further side effects or return behavior.

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

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

Two concise sentences front-load the purpose and follow with a practical usage tip. Every word 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 simple single-parameter tool with annotations and no output schema, the description covers purpose, session scope, and how to obtain the parameter value. It is complete for the agent's needs.

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 input schema fully documents workspaceId as a string, and the description enriches it by telling the user how to find valid workspace IDs via find(type='workspaces'). This provides useful value 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 clearly states the action ('Switch active workspace') and the scope ('for this session'), distinguishing it from project-level tools. The verb+resource combination is unambiguous and specific, with no ambiguity about what the tool does.

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

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

It provides a clear prerequisite by directing users to find(type='workspaces') to list available options. Since there are no alternative workspace-switching tools among siblings, this is sufficient context, though it lacks an explicit when-not-to-use statement.

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 states 'Screenshots removed from markdown are deleted,' indicating destructive behavior, while annotations declare destructiveHint: false. This is a direct contradiction, so transparency scores 1.

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 concise sentences cover purpose, screenshot behavior, and usage workflow 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?

Covers what is updated, screenshot handling, and how to use it. No output schema is present, but update tools often need not describe return. The workflow advice adds completeness.

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%, but description adds meaning by explaining that order in markdown defines final order and screenshots are kept/deleted based on presence, elaborating on the markdown parameter's 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?

The description states 'Update article text content from markdown,' which is a specific verb+resource. It also details screenshot placeholder handling, distinguishing this tool from related article media 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?

Explicitly instructs to 'Get the current article first with get_article, modify the markdown, then call this,' providing a clear workflow and identifying the prerequisite sibling 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?

The description adds meaningful behavioral context beyond the sparse annotations: it discloses that render=true is non-mutating, that updates mutate metadata, and that deletion is not a direct operation but occurs indirectly when media is unreferenced in markdown and pruned server-side. This gives the agent a clear mental model of the tool's side effects and the system's source-of-truth behavior. 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 efficiently structured: a clear opening sentence, two concise bullets for primary usage, and a short paragraph explaining deletion. Every sentence serves a distinct purpose (action, update modes, delete alternative), with no fluff or redundancy. The format is easy to scan and front-loads the most critical 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?

The description handles the tool's dual update/inspect functionality and explicitly covers deletion behavior, which is critical given the source-of-truth model. However, it does not describe the return value of a successful update (only that render=true returns details and a PNG preview). In the absence of an output schema, a note about mutation responses would make it fully complete. Still, for the tool's complexity, it covers the main usage scenarios well.

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 input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds some value by listing which parameters trigger updates and reiterating that render=true must be used with no other updates, but this nuance is already present in the schema's render description. The description does not introduce additional parameter-level details, so it neither exceeds nor falls below 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 immediately states the action with a specific verb and resource: 'Update an article image/GIF (screenshot), or inspect its current state.' It further clarifies the scope (metadata updates via zoom/crop/shapes) and explicitly distinguishes itself from the delete action, which is handled by update_article. This makes the purpose unambiguous and well-differentiated from siblings.

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

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

The description provides explicit usage context: 'Provide one or more of zoom_factor, crop, shapes to change metadata' and 'Pass render=true (with no other updates) to fetch the current details without mutating.' It also gives a clear alternative for deletion: 'call update_article with markdown that omits the <SCREENSHOT id> reference.' This not only says when to use the tool but also when not to use it, naming the alternative 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?

The description discloses the partial-update behavior ('Only fields you pass are changed; omitted fields are preserved'), which is a key behavioral trait beyond the annotations. It also notes that the per-entry shape matches this tool's args, helping the agent understand the data flow. Annotations already indicate it's writable and not destructive, so this adds valuable context without 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?

The description is concise and front-loaded, with the primary purpose in the first sentence. Each subsequent sentence adds essential guidance: reading existing data, partial update semantics, and the deletion alternative. There is no fluff or redundant information.

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

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

For a tool with 10 parameters and no output schema, the description is highly complete. It explains how to obtain the necessary IDs, which fields are updatable in general, and how to avoid losing the track id. It also differentiates from the deletion alternative, covering the full usage context an agent needs.

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 meaning by grouping parameters into categories ('volume, fades, timing, loop') and explaining that the args match `get_project.audio_tracks` entries, which helps the agent map values from a read operation to this update call. This goes beyond the individual schema descriptions.

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

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

The description starts with 'Mutate fields on an existing music/SFX track by id', which precisely states the action (update), resource (audio track), and scope (existing by id). It clearly distinguishes from siblings like `add_audio` (create) and `remove_from_project` (delete) by explicitly referencing them.

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

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

The description provides explicit workflow guidance: read existing tracks via `get_project.audio_tracks`, then update by passing the same shape. It also tells the agent when not to use this tool ('To delete a track entirely, use `remove_from_project(target='audio')` instead'), making the alternatives clear.

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 basic annotations (readOnlyHint=false), the description discloses important behavioral traits: mute behavior via voiceover_volume, transition playing on the outgoing clip, position move application order, video_styling field merging, and the fact that there is no 'delete voiceover' tool. These details are not inferable from the schema or annotations and significantly help the agent predict side effects.

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 tightly organized with a summary, entry format, per-field details, and a concurrency section. Every sentence adds value and addresses real usage pitfalls. Despite the volume, it is well-structured and easy to scan, which is appropriate for a batch tool with six updateable field types.

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 complexity (batch updates, many parameter interactions, ordering constraints) and the absence of an output schema, the description fully covers what an agent needs to know: field semantics, ordering rules, concurrency limitations, and integration with sibling tools like add_audio. It leaves no critical gap for correct invocation.

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

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

Even though schema coverage is 100%, the description adds crucial semantics: explains that voiceover_volume 0 mutes while preserving word timings, describes transition direction defaults per type, clarifies that background_color keeps the pattern while background replaces it, and specifies video_styling merge behavior. This goes far beyond the schema 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?

Describes exactly what the tool does: 'Update one or more clips in a single call' with a specific list of fields (background, transition, duration, etc.). Clearly distinguishes from sibling tools like add_clips (add vs update) and update_elements (element vs clip). The instruction 'Always batch.' reinforces a distinct usage pattern.

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

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

Provides explicit guidance: 'Always batch', 'keep reorders in a separate call from property edits', and 'run update_clips BEFORE add_audio'. Also warns against concurrent execution with element/voiceover edits or whole-project mutations. This gives clear when-to-use and when-not-to-use context that 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 mark destructiveHint=true, but the description goes further by specifying exactly what is destructive: 'Existing files at the same path are overwritten' and 'Set content to null to DELETE this path.' It also explains that metadata is patched rather than replaced, providing valuable behavioral context beyond the structured 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 and efficient. It opens with the main purpose, then organizes metadata and file mutation details in clear bullet-like sections. Every sentence adds useful information without redundancy, making it easy to scan and understand.

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 this complexity (multiple mutation types, patching semantics, destructive actions), the description covers all necessary aspects: metadata patch behavior, file write/delete modes, URL sourcing, and overwrite behavior. No output schema exists, but the description adequately covers what the tool does and how to invoke 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?

Although schema coverage is 100%, the description adds significant semantic value. It explains the relationship between metadata fields and patch behavior, details the file mutation structure, clarifies base64 encoding, and documents the special use of content: null for deletion. These are insights not derivable from the raw 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 starts with a clear, specific verb+resource: 'Update a clueprint's metadata and/or file contents in one call.' It distinguishes this from sibling update tools (update_project, update_article) by focusing on clueprint-specific operations and by detailing the dual metadata/file update capability that is unique to this tool.

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 guidance on how to use different file mutation modes, including when to use source_url vs inline content ('Use this instead of inline content for large/binary files'). It also clarifies metadata patching semantics and the significance of content: null for deletion, giving clear context for when and how to use each parameter.

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 details partial success, sequential application within a call, grouping z-order effects, keyframe clearing semantics (null vs empty array), and locking behavior under concurrency. Annotations only say readOnly=false and destructive=false, so no contradiction; the text adds significant behavioral context beyond safety flags.

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 broken into topic paragraphs (purpose, grouping, concurrency, keyframes, text). It is front-loaded with the essential purpose and batch requirement. Some details could be condensed, but the complexity of the tool justifies the length.

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

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

Given the tool's complexity, the description covers parameter semantics, concurrency, grouping, keyframes, and even return hints for save_as_component. Without an output schema, it does not fully define the response format for normal updates, but 'partial success is fine' implies per-item results. This is complete enough for an agent to invoke correctly.

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

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

Schema descriptions are 100% covered, but the description adds crucial semantics: placement of `keyframes` as a top-level sibling, grouping via `group` with empty-string semantics, the `fit_to_lines` algorithm (widen then font-shrink), and `save_as_component` behavior. It also clarifies alignment origin interplay with x/y. This exceeds the schema baseline.

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

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

The description opens with a specific verb and resource: 'Update many elements across one or more clips in a single tool call.' It clearly distinguishes itself from add_elements and the per-element tool it replaces. The title is generic but the description is precise and action-oriented.

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

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

The description explicitly states this is the replacement for the per-element tool and mandates batching ('always batch'). It provides concurrency guidance with explicit do-not-run conditions (update_clips, add_audio, update_project) and tells the agent to consult get_element_schema for settable fields. This gives clear when-to-use and exclusions.

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 behaviors beyond the annotations: partial updates ('Only fields you provide are changed'), the special empty-string folder_id to move to workspace root, the canvas-fit logic for aspect ratios (1920×1080 container, resulting pixel dimensions), and the fact that element coordinates are stored as fractions and reflow automatically without being rewritten. It also explicitly warns about the whole-project conflict domain and serialization requirements, which is critical for correct concurrent invocation.

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: it opens with the purpose sentence, then uses short paragraphs and a bullet list for common aspect ratios. Every sentence adds value—special folder_id behavior, canvas math, coordinate reflow, and concurrency constraints. Despite its length, the structure makes it easy to scan, and the concurrency warning is clearly separated.

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 tool involves nuanced side effects (aspect ratio reflow, coordinate system, concurrency), and the description fully explains these, including common-use examples and constraints. It does not explicitly state the return value, but given the lack of an output schema and the straightforward nature of an update operation, this is a minor omission. Overall, it provides all the information an agent needs 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?

The description adds significant meaning beyond the schema's parameter descriptions. For aspect_ratio, it gives a concrete mapping table with computed canvas sizes (e.g., '9:16' → 608×1080) and use cases. It clarifies that folder_id='' moves to workspace root and that all parameters are optional partial updates. These details are not present in the schema and materially help an agent understand the effect of parameter choices.

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 begins with 'Update a project's metadata: rename, change description, move to a different folder, or change aspect ratio.' This clearly identifies the action (update) and resource (project metadata), listing the specific fields affected. It also distinguishes itself from sibling update_* tools by targeting project metadata rather than articles, audio, clips, or 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 states exactly when to use the tool (renaming, changing description, moving folders, changing aspect ratio) and adds partial-update semantics: 'Only fields you provide are changed.' It also provides clear concurrency guidance: 'Do not run it in parallel with ANY other mutation on the same project_id,' explicitly advising serialization. It does not name alternative sibling tools, but the context of project-level updates is sufficient for an agent to choose it appropriately.

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 include readOnlyHint=false and openWorldHint=true, and the description thoroughly explains the underlying behavior: the file_name mode 'Returns an upload URL on Clueso's OWN base domain + a ready-to-run curl' and requires the client to PUT bytes to that domain, avoiding the need for direct S3 access. It also clarifies server-side fetching for file_url and one-token-many-files semantics for hosted uploads. This goes well beyond what annotations convey.

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

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

The description is front-loaded with the purpose and a clear three-mode breakdown, then proceeds to integration details. It is longer than typical but each section serves a purpose; however, some redundancy exists (e.g., repeated 'call once for all files') and the downstream usage section could be condensed without losing 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?

For a tool with four optional parameters, no output schema, and moderate complexity, the description covers everything: mode selection, prerequisites (PUT capability), the mcp_upload_id lifecycle, and specific downstream tools (add_elements, update_elements, add_audio, add_clips, add_article_media, analyze_audio). It even notes update-path-only semantics for parameter_values. This is exceptionally 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% with per-parameter descriptions, so the baseline is 3. The description adds meaningful mode-based context (e.g., file_name is for a single file and returns a curl command; file_names is guidance for the hosted page; request_hosted_upload is a boolean that toggles the UI mode). This enriches the schema without repeating it 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 description opens with 'Upload one or more files to Clueso' and then enumerates three distinct modes (file_name, file_url, request_hosted_upload), each with a clear use case. This specific verb+resource+scope clearly differentiates it from sibling tools that consume uploads, such as add_elements or add_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 provides explicit when-to-use guidance for each mode: 'Prefer this whenever there's no human at a browser' for file_name, 'Use when the file is already on the open web' for file_url, and 'use ONLY when a human should pick files in a browser' for request_hosted_upload. It also describes how to chain with check_uploads and which downstream tools accept the returned mcp_upload_id.

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 far beyond the minimal annotations (readOnly=false, destructive=false) by disclosing async TTS behavior ('returns immediately'), the single-save batching for text actions, and the critical retiming side effect ('clip's duration is reset to the spoken audio length' with element time past the audio end being cut). It also explains per-guide locking and serialization semantics, which is rich behavioral context.

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

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

The description is well-structured: a one-sentence purpose, a concise bulleted action list, a brief ordering note, and then two clearly labeled caveat blocks (IMPORTANT and Concurrency). Every sentence carries essential information, and the layout front-loads the primary purpose before diving into edge-case guidance. Despite its length, there is 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?

Given the tool's complexity (three action types, async processing, timing side effects, concurrency constraints) and the absence of an output schema, the description is remarkably complete. It covers what the tool does, how entries are processed, what to expect as return behavior, important retiming consequences, and explicit concurrency rules, leaving little ambiguity for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by mapping each action variant to its required parameters (e.g., set_text needs clip_index+text, generate_speech needs clip_id) and clarifying that entries are applied in order. This helps the agent construct valid entries combinations beyond the schema's per-property descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Set voiceover text and/or trigger speech generation for any number of clips in a single call.' It clearly distinguishes itself from siblings like set_voice by emphasizing batch capability and the dual text/TTS operations, and enumerates three concrete action types.

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 context: 'any number of clips in a single call' and the three action variants. It gives detailed concurrency guidance, naming specific tools to avoid (update_clips, add_audio, update_project) and explaining when it is safe to fan out across subagents. It also references estimate_duration as a timing prerequisite, which serves as an alternative/precursor.

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