Clueso

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds value by explaining that the tool returns a screenshot_id and requires a subsequent update_article call to place the media. It also clarifies the conditional parameter requirements, though it could be more explicit about error handling or 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 concise and well-structured, with a clear main statement followed by bullet-point details for each kind. Every sentence adds value, and the total length is appropriate for the 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?

Given the tool's complexity (5 parameters, conditional logic, no output schema), the description covers the essential workflow: adding media, getting an ID, and placing it via update_article. It mentions prerequisites for gif but lacks explicit error scenarios or confirmation that the media is stored. Still, it is largely complete for practical use.

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 has 100% coverage, but the description significantly enhances parameter understanding by explaining the conditional dependencies: for kind='image', one of timestamp or mcp_upload_id is required; for kind='gif', timestamp and duration are used. It also links mcp_upload_id to the upload tool, which the schema does not.

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

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

The description clearly states the tool adds a screenshot or GIF to an article, specifying the return value (screenshot_id) and how to use it with update_article. This distinguishes it from sibling tools like upload_file or generate_media by focusing on article media attachment.

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 detailed conditional usage for the two modes (image vs. gif), including prerequisites (e.g., project must have a video clip for gif). However, it does not explicitly compare this tool to alternatives like upload_file, generate_media, or update_article_media, leaving the agent to infer when to use this vs. other 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?

Annotations provide readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description goes far beyond by explaining the non-clip-slot nature, differentiating music vs sfx behaviors, and detailing critical runtime semantics like guide_end_time being captured at call time and not auto-extending. No contradiction with annotations.

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

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

The description is well-structured with type-specific bullet points, a concurrency note, and a clear front-loaded purpose. While fairly long, every sentence adds value and aligns with the tool's complexity (14 params, two types). Could be slightly tighter, but the organization is logical and easy to scan.

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

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

Given 14 parameters, 2 required, no output schema, and complex behavior (type-specific logic, concurrency domain, default timing caveats), the description covers the necessary details for correct invocation. It addresses edge cases (legacy sfx_key, mcp_upload_id, guide_end_time capture behavior) and provides actionable guidance for an AI 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% already, but the description adds significant extra meaning: for src, it explains the opaque Freesound handle and mcp_upload_id usage; for source_duration, it cites analyze_audio as an alternative; for guide_end_time, it elaborates on the capture-time default. This greatly enhances the agent's understanding beyond 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 uses a specific verb ('Add') and clearly identifies the resource as a 'project-level audio layer over all clips'. It explicitly states it does NOT consume a clip slot, distinguishing it from the sibling tool add_clips. The contrast with add_clips(kind='video') for audio-as-clip further sharpens purpose clarity.

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 use the tool ('background music or a soundtrack that should play under the existing timeline') and when NOT to use it (for inserting an audio file as its own sequential clip, referencing add_clips). It also provides concurrency guidance ('serialize; do not run in parallel with ANY other mutation') and warns about guide_end_time behavior. This is comprehensive and actionable.

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 (readOnlyHint=false, destructiveHint=false) are basic, but the description adds extensive behavioral details: concurrency constraints, 24h caching, background pipeline for video, and the note that create_project already creates clip 0. No contradictions.

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

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

The description is well-structured with clear sections for each kind, but it is somewhat long due to thorough details (e.g., caching, concurrency). Every sentence contributes value, though minor trimming could improve conciseness.

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

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

Covers all aspects: parameter usage, side effects, ordering, concurrency, alternatives, and caching behavior. However, it lacks explicit mention of the return value (what the tool outputs after creating clips), which would be useful given no output schema. Still very complete overall.

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%, yet the description adds significant context: for blank clips, it explains that background/transition can be set at creation; for video kind, clarifies mime_type default and the effect of omitting cuts; for pptx, slide_indices optional. All parameter meanings are enriched beyond raw 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 creates new clips on a project and distinguishes three sources (blank, pptx, video) with explicit use cases. It differentiates from sibling tools like add_elements for video overlays and add_audio for background music.

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 tells when to use each kind and when not (e.g., for overlays use add_elements, for background music use add_audio). Provides concurrency advice: serialize mutations on the same project, do not run in parallel with other mutations.

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 key behavioral trait that comments are attributed to 'Clueso AI' rather than the user, which is not evident from the annotations alone. Annotations already indicate that the tool is not read-only, not destructive, and not open-world, so the description adds value by revealing the attribution behavior. 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 two sentences long, with the first sentence stating the core action and attribution, and the second sentence explaining the two usage modes. Every sentence adds value, and there is no redundant or extraneous 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?

Given the tool's moderate complexity (4 parameters, 2 required, no output schema, no nested objects), the description covers the essential behavioral aspects and usage contexts. It does not explain the return value, but with no output schema, the agent can infer success/failure from typical API patterns. It is complete enough 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?

The schema already provides 100% coverage for all four parameters with clear descriptions, so the baseline is a 3. The description does not add any additional semantic detail beyond what the schema offers—it only restates the purpose of clip_id and clip_timestamp in context. No deduction or bonus is warranted.

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 ('post a review comment'), the target ('on a project'), and the attribution ('Clueso AI'). It further distinguishes the two modes (project-level or pinned to a clip with an optional timestamp), which adds precision and helps differentiate it from any sibling 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 explains when to use this tool—'to leave feedback, suggestions, or notes'—and explicitly describes the two usage contexts (project-level vs. pinned to a clip). It does not mention when NOT to use it or list any alternative sibling tools, which is acceptable given the clear context and the lack of obvious overlapping tools in the sibling list.

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?

Despite annotations being present (readOnlyHint: false, destructiveHint: false), the description adds extraordinary behavioral detail: it explains the per-guide lock and merge semantics for concurrency, clarifies that partial success is fine (returns one result per input item), describes ordering ('Items within one call are applied in order'), and notes that clip_id is accepted but unused for most element types. The description goes far 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 well-organized with clear section headers (element-type quirks, position origin, animation, grouping, concurrency, reuse instead of rebuilding). It is longer than ideal, but every section provides critical, non-obvious information that an agent would need to use the tool correctly. Minor deduction for density; each sentence 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?

Given the tool's high complexity (many element types, animation keyframes, component system, grouping, concurrency issues), the description is remarkably complete. It covers element-type-specific behaviors, keyframe structure and constraints (≥2 entries, interpolation defaults, property-level overrides), component re-use workflow (find, insert via component_id, customize with update_elements), grouping semantics (z-order, new groups take first member's slot, animations cannot be grouped immediately), and concurrency conflict domains. No gaps identified.

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 description coverage is 100% (all parameters documented in the schema), the description adds significant meaning: it explains the origin semantics for position (top-left vs center vs top-right based on alignment), clarifies that zoom ignores x/y/width/height and uses center_x/center_y, notes that image requires x/y/width/height while clip_id is unused, states that animation defaults to full canvas dimensions, and explains that width/height are not keyframable on text. It also describes the relationship between component_id and element_type/type_data (mutually exclusive), and adds context about grouping behavior that is not 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 the tool adds elements to clips and immediately distinguishes itself from a per-element tool by saying 'Replaces the per-element tool — always batch.' It specifies the primary action (adding many elements across clips in a single call) and contrasts with sibling tools like update_elements and remove_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 provides extensive usage guidance: it tells when to use get_element_schema first, explains the workflow for reusing components versus generating new ones (component_id vs base_component_id), details grouping behavior, and gives explicit concurrency warnings including which tools to avoid running simultaneously (update_clips, add_clips, remove_clip, split_clip, duplicate_clip, add_audio, update_project). This is exemplary usage 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?

The annotations already indicate destructiveHint=false, readOnlyHint=false, and openWorldHint=false, so the description does not need to cover safety again. However, the description adds valuable behavioral context: it explains how word matching works (case-insensitive, punctuation-stripped, first match by default), the role of the occurrence parameter, and the timestamp auto-mapping behavior. It also discloses constraints (clip must be video with source recording, transcript must contain the word) and error handling (word_not_found with excerpt). This enriches the agent's understanding beyond annotations, though a minor gap is lack of detail on what happens after insertion (e.g., is the clip modified in place? Are there side effects on other sync points? Still, 4 is justified for solid 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 structured with a brief introduction, bullet-style usage guidance, and detailed notes on matching and constraints. The information is front-loaded with the core action and when-to-use, followed by specifics. It is not excessively verbose, but the 'How matching works' section could be slightly tighter. Overall, it earns its length and is easy to parse.

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 (7 parameters, 3 required, no output schema), the description covers the core semantics, matching logic, constraints, and error handling. It explains inputs well but does not describe the output or return value (e.g., what the agent receives after success, or how to interpret the result). Since there is no output schema, the agent would benefit from knowing the response format (e.g., sync point ID, confirmation). Nonetheless, for a mutation tool with no output schema, the description is largely complete for guiding correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters' types and basic roles. The description adds significant meaning beyond the schema: it explains the matching semantics for 'word' (punctuation-stripped, first match strategy), clarifies that 'occurrence' is 1-indexed and required for repeated words, and describes the auto-mapping of timestamp_seconds when generated_timestamps exist. It also implies the optionality of sync_point_name and the fallback between clip_id and clip_index. These details are not present in the schema alone and help the agent use parameters correctly. A score of 5 would require explicit examples or edge-case handling, but 4 is strong.

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 the specific verb 'Insert' and the resource 'sync marker on a clip's transcript', clearly distinguishing its purpose from sibling tools like 'auto_sync' (which runs automatic sync) and 'split_clip' (which cuts the clip). It states the tool adds a sync point at a specific word and timestamp, leaving no ambiguity.

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 use this tool: 'when the user is explicit about where the camera should pause/cut' and 'when auto_sync ran but missed a step you care about'. It also implies when not to use it (rely on auto_sync for automatic syncing) and gives context about matching behavior and constraints, providing clear guidance for the agent.

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 set readOnlyHint=true and destructiveHint=false, so the tool is clearly read-only. The description goes beyond this by noting behavioral traits: transcript works on both speech and lyrics by routing to a music-aware provider, features.has_speech may report false on pure music while transcript still extracts lyrics, and beats returns empty for non-music. This adds useful context beyond annotations, though it doesn't cover all edge cases thoroughly.

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 header, bullet points for modes, and organized paragraphs for source and optional parameters. Every sentence adds value, and the front-loaded mode descriptions make scanning easy. No wasted words—concise yet comprehensive.

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 (7 parameters, 1 required, nested objects, 4 modes with specific behaviors) and absence of an output schema, the description is remarkably complete. It covers all modes, edge cases (music handling, empty beats), source options, time range, and notes caveats like false negatives. An AI agent can confidently invoke this tool without additional clarification.

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 how mode values work (e.g., transcript produces words[{w,start_ms,end_ms}]), source constraints, and offering default behaviors (default whole file for range). However, it does not explain all nested options (silences_options, transcript_options) in full detail, lacking a small step to a perfect score.

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

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

The description clearly states the tool analyzes audio files and enumerates four distinct modes (transcript, silences, beats, features) with specific use cases. It differentiates from siblings like add_audio (which adds audio to a project) and check_uploads (which checks upload status), and provides enough specificity for an AI agent to understand the scope.

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

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

The description provides explicit guidance on when to use each mode (e.g., 'Use for auto-trim, smart-split' for silences, 'align animations/zooms to a beat' for beats), mentions a cheap dispatcher mode features, and gives alternatives like 'call once to decide which other mode to use'. It also clarifies source options (mcp_upload_id vs file_url) and optional time range, fully satisfying 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?

Adds significant behavioral details beyond annotations: async nature, immediate return of status enum, delayed insertion of sync markers, polling recommendation, and platform-wide concurrency cap. Annotations already indicate destructiveness, but the description enriches understanding.

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?

Approximately 100 words, well-structured into three logical paragraphs. Every sentence adds value: purpose, async behavior, capacity, and usage context. No redundancy or 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?

Covers purpose, async behavior, concurrency, and usage context. References external docs for more detail. However, does not enumerate possible status enum values returned from the pre-flight, which is a minor gap given no output schema.

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

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

Schema coverage is 100% with two parameters. The description does not add any additional meaning beyond the parameter names and brief descriptions in the schema. Baseline score 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?

Clearly states the verb 'run the auto-sync pipeline' and resource 'clip with source recording'. Distinguishes from sibling 'add_sync_point' by description of automation. The title 'Auto-generate sync points' aligns with the description.

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 strong context: sync points are required for TTS, and describes capacity limits and async behavior. Implicitly differentiates from manual sync point addition. However, lacks explicit when-not-to-use guidance or alternative tool mentions.

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 the description adds that it returns one mcp_upload_id per file and that the token covers all files. No contradictions, but no additional behavioral traits like error handling or pagination are disclosed.

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

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

Three sentences, front-loaded with the main action, no extraneous words. Each sentence serves a distinct purpose: action, returns, and usage guidance.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the essential workflow and return value. It could mention edge cases like empty uploads but is otherwise complete.

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

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

Schema description covers 100% of the parameter, and the description adds context about the token's scope ('the token covers all files they dropped on the page'), which goes beyond the schema's definition.

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 'Fetch all files' and the resource 'uploaded via hosted upload page', and distinguishes from siblings by specifying it returns mcp_upload_id per file to be passed to other tools like add_clips and add_article_media.

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

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

Explicitly says when to call ('once after the user confirms they are done uploading'), explains that the token covers all files, and instructs to pass each returned ID to the appropriate tool for further processing.

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, so the description is not required to repeat that. It adds value by disclosing the automatic extraction behavior ('guide data is automatically extracted clip-by-clip') and the structured folder categories, which are behavioral traits beyond the annotations. No contradiction detected.

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

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

Three sentences, all essential: definition, usage advice, and conditional behavior. No filler, front-loaded with the primary purpose. Each sentence 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?

The description adequately covers the purpose, usage, and a key side effect (auto-extraction). It references external documentation for full structure, which is acceptable. However, it does not mention what the tool returns (e.g., clueprint ID) nor any next steps. Given no output schema, a slight gap exists, but overall it 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 baseline is 3. The description adds meaningful extra context: for source_guide_ids, it specifies 'clip-by-clip' extraction and 'reference material', which the schema lacks. It also orients the agent toward folder categories, though these are not directly tied to a parameter. This exceeds 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 clearly states 'Create a new clueprint' with a specific verb and resource. It defines a clueprint as a 'reusable video template' and explains its structure (file directory with design notes, rules, screenshots). This effectively distinguishes it from sibling tools like get_clueprint or update_clueprint.

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

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

The description provides usage hints such as using human-readable folder categories and referencing the system instructions, but it does not explicitly compare this tool to siblings like create_project. There is no guidance on when not to use it or alternatives, leaving the agent to infer from the sibling list. The conditional behavior with source_guide_ids offers some contextual 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?

The description discloses behavioral details beyond annotations: the project starts with one blank clip at index 0 with default short duration, and the tool returns projectId and initialClipId. Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness, so the description adds useful context about initial state and return values.

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 sentences: first states purpose and return, second lists follow-up tools, third covers optional folder and description. It is front-loaded, every sentence adds value, and there is no 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?

Given the tool has 3 optional parameters and no output schema, the description covers initial state, return values, and post-creation workflow. It does not explain potential constraints (e.g., title uniqueness) or error cases, but for a simple creation tool, the coverage is reasonably complete and actionable for an AI agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by explaining the folder_id context (use find to discover IDs, omit for root) and mentioning description at creation, but these are largely redundant with the schema descriptions. No additional semantic depth is provided beyond what the schema already offers.

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 'Create a new blank Clueso project' with a specific verb and resource. It distinguishes from sibling tools by outlining post-creation steps (update_clips, add_clips, etc.), implying this tool is for initial creation only. The return values (projectId and initialClipId) are also specified.

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

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

The description provides explicit guidance on when to use this tool (for initial creation) and references sibling tools (update_clips, add_clips, add_elements, add_audio) for subsequent actions. It also advises on folder placement using find(type='folders'). However, it does not explicitly state when not to use it (e.g., for duplicating a project), though this is implied by the listed alternatives.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which are minimal. The description compensates thoroughly by disclosing S3 asset re-hosting, independence from source project (deleting source later won't break the new clip), insertion behavior, return value shape (clip_id and final index), and concurrency domain (entire target project as a conflict domain). 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?

Extremely concise and well-structured: one core sentence, then bullet-point-style sections for modes, insertion, returns, and concurrency. Every sentence provides unique guidance with 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?

For a 4-param mutation tool with no output schema and only three basic annotations, the description fully covers all necessary behavioral details: both modes, asset independence, insertion, return value, and concurrency. Nothing critical is missing for an agent to invoke this tool correctly.

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

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

Schema has 100% description coverage, so baseline is 3. The description adds value by explaining the semantics of parameter combinations (e.g., when to omit source_project_id) and the effect of after_clip_id, which goes beyond the schema's field-level descriptions. However, it doesn't reference the target_project_id parameter explicitly beyond its brief schema description, so the added value is strong but not exhaustive.

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 a clear verb ('Clone') and resource ('one clip'), and immediately distinguishes two distinct modes (same-project vs cross-project) with precise parameter guidance. This differentiates it from sibling tools like duplicate_project 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?

Explicitly states when to use different parameter combinations for same-project vs cross-project duplication, and gives specific guidance on insertion behavior via after_clip_id. Also provides concurrency guidance ('serialize; do not run in parallel'), which helps the agent decide usage timing.

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 significant value beyond annotations: it states the copy has its own S3 namespace (so source changes don't affect the duplicate), describes the default title creation logic, explains folder placement behavior, mentions return values (id, title), and provides concurrency constraints. This fully characterizes the tool's behavior without contradicting the annotations.

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

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

The description is well-structured with clear sections (main action, defaults, return value, concurrency). It is slightly verbose but every sentence earns its place by providing essential guidance. Front-loading the main action helps quick scanning.

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 has 3 parameters, no output schema, and adequate annotations, the description covers the major behavioral aspects: copy scope, isolation, defaults, return format, and serialization advice. It is complete enough for an agent to use correctly. Minor omissions (e.g., error cases, permission requirements) are acceptable given the annotations and 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%, but the description adds crucial context: the interplay between new_title and folder_id (e.g., title preserved when explicit folder_id given, otherwise '(copy)' suffix), and the folder_id behavior (same folder if omitted, empty string moves to root). This explains edge cases and defaults that 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 uses a specific verb ('Clone') and resource ('entire project'), lists what is copied (clips, voiceovers, assets, metadata), and distinguishes from related tools like create_project and duplicate_clip by implying full project duplication. The S3 namespace detail further clarifies the isolation behavior.

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 defaults for when to omit new_title or folder_id, and gives explicit concurrency guidance: serialize against other mutations on the same source_project_id. It implicitly tells when to use this tool (full project copy) vs alternatives (e.g., duplicate_clip for single clips), but 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?

Annotations already declare readOnlyHint: true and destructiveHint: false, so the description's revelation that this is a non-destructive estimation (no actual clips created) aligns perfectly. The description adds the key behavioral detail of 150 words/minute, which is valuable beyond annotations.

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

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

Two sentences with zero waste. The first sentence states the verb and resource, the second explains the input and output structure. Every word earns its place, and the key speed assumption is front-loaded with a parenthetical.

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, annotated read-only tool with no output schema, the description covers the purpose, input structure, output ordering, and intended use. Could mention what happens with empty texts or unusual characters, but given the low complexity, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that the texts are voiceover texts and that one string corresponds to one clip, but this mostly restates the schema's description. No significant new meaning beyond the schema.

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

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

The description clearly states the tool estimates voiceover duration for one or many clips at once, with a specific speed approximation (~150 words/minute). It differentiates itself from siblings like add_clips or voiceover_batch by focusing on estimation rather than actual 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?

The description explains when to use this tool: before adding clips, by passing an array of voiceover texts. It mentions the returned durations are 'ready for add_clips', implying a workflow. No explicit exclusions or alternatives are given, but the context is clear.

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

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

Annotations indicate no read-only or destructive behavior, and the description adds value by clarifying the asynchronous nature ('returns immediately... background'), the defaults for resolution, fps, captions, and language, and where the user finds the result. This goes beyond annotations to explain the background pipeline behavior.

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

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

The description is extremely concise—two short sentences plus a defaults summary. Each sentence provides essential information (async behavior, where to find output, defaults, guidance on overrides) with no filler. It is front-loaded with the main action and outcome.

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 4 parameters and no output schema, the description covers the core behavior, defaults, and async feedback mechanism. It could mention what happens on error (e.g., if export fails) or the output schema (export_id type), but this is minor. The context is mostly complete for a tool with 100% schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by stating defaults for all optional parameters (1080p, 30fps, no captions) and advises passing overrides only when needed, which prevents agents from redundantly specifying defaults. It also mentions language (English) as a hidden default, which is not 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 kicks off a video export of a project, distinguishing it from other tools like 'get_project' or 'update_project'. It uses specific verbs ('kick off') and resources ('video export of the project'), and mentions the asynchronous return of an 'export_id', which differentiates it from synchronous operations.

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

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

The description provides clear context on when to use this tool (to start an export) and notes that overrides are only needed for non-default values. However, it does not explicitly mention when not to use it or alternatives among the 39 sibling tools, such as 'estimate_duration' which might be used first to check feasibility.

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, but the description adds significant behavioral details: return format, special handling of stock media results (opaque handles, safe_src, preview_url), pagination behavior for clueprints, and constraints like 'stock media ignores these (fixed shortlist)'. 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 bullet points, clear sections, and indentation for readability. However, it is verbose (several paragraphs), and some details could be condensed without losing meaning. Every sentence earns its place, but the length slightly impacts rapid scanning.

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 (19 parameters, 12 resource types, stock media integration, no output schema), the description covers all necessary aspects: parameter behavior, result handling, constraints, and consumption guidance. It even addresses edge cases like 'stock results are a short described shortlist' and 'duration is in seconds'. No gaps identified.

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 the description adds immense semantic value beyond the schema: it explains how 'query' behaves differently per type (semantic search for clueprints, case-insensitive substring for others), provider selection strategy, and parameter interactions (e.g., 'image_type only with provider=pixabay'). This transforms the schema from a list of options into a usable decision tree.

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 'Find any resource in Clueso by type, optionally filtered by name or exact id. One tool for listing and searching across the workspace.' This clearly identifies the specific verb (find), resource (any resource in Clueso), and scope (listing and searching), and distinguishes it from siblings as no other tool is a generic finder.

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 when-to-use guidance, including detailed instructions for stock media provider selection, pagination behavior ('page through rather than assuming the first page is everything'), and explicit warnings about limitations (e.g., 'tiers above 1080p can exceed its ~200MB source cap and fail'). It also gives context on when to use alternatives (e.g., 'use safe_src... in add_elements').

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

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

The description reveals that generation is asynchronous, with immediate element_id creation and background rendering, and instructs to poll get_clip for completion. It also discloses side effects of voiceover_text (sets voiceover and triggers speech generation). These details go well beyond the sparse annotations (readOnlyHint=false, etc.) and provide 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 concise and well-structured: a one-line summary, bulleted breakdown by kind, async behavior note, and a usage tip. Every sentence is necessary and adds value, with no redundancy or 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?

The description covers the two generation modes, async behavior with polling instructions, and alternatives. It is thorough for a tool with 15 parameters and complex behavior. However, it omits details on error handling, timeouts, or what happens on generation failure, which would enhance 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 description coverage is 100%, so each parameter is already documented. However, the tool description adds significant extra meaning: grouping parameters by kind, explaining optional parameters' sources (e.g., style_id from find), mutual exclusivity of reference_image_url and mcp_upload_id, and the side effect of voiceover_text. This raises the value above baseline 3.

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

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

The description clearly states the tool generates AI images or canvas-code animations into a clip. It distinguishes between two kinds (image and animation) and explicitly contrasts with the sibling tool add_elements for uploaded media, making the boundary unambiguous.

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

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

The description provides explicit guidance: 'use this tool whenever the user asks for a generated, AI, or create me a visual' and 'for uploaded photos / logos / icons / GIFs, use add_elements'. It also explains when to use each kind and optional parameters, giving clear decision 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?

Annotations already confirm readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds valuable context about the markdown format and how screenshots are represented ('Screenshots appear as <SCREENSHOT {id}> placeholders'), which annotations do not 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?

The description is two sentences, front-loaded with the core purpose, and every word earns its place. No fluff 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?

Given the simple 1-param, read-only tool with full schema annotation, the description is mostly complete. It explains the return format and screenshot handling. However, it could mention if the markdown includes metadata or if any special error cases exist (e.g., article not found), but this is not a critical gap.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter 'project_id'. The description does not add meaning beyond what the schema provides (e.g., no context on where to find the project ID or what it represents). Baseline 3 is appropriate.

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

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

The description uses specific verbs ('Get the article content') and identifies the resource ('article') and return format ('as markdown'). It distinguishes itself from sibling tools like 'update_article' and 'get_clip' by clearly indicating a read operation returning content.

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 this tool is for reading article content and nothing else, but it does not explicitly state when to use this vs. other read tools like 'get_project' or 'get_clip'. No exclusions or alternatives are mentioned.

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 declare `readOnlyHint: true` and `destructiveHint: false`, so the description doesn't need to restate safety. Instead, it adds enormous value by detailing the tool's expensive nature ('A full read is large'), the relationship between `select` and `render` as independent axes, and how keyframes and voiceover data are returned. This goes far beyond the annotations.

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

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

The description is well-structured with clear sections and examples, making it highly informative. However, it is quite lengthy (over 600 words). While every sentence adds value, the sheer volume slightly impacts conciseness; a slightly tighter version could retain clarity while being more scannable.

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

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

Given the tool's complexity (5 parameters, nested objects, no output schema), the description is remarkably complete. It covers what the tool reads, how to control the output via `select` and `element_ids`, how `render` works independently, and the structure of the returned elements. The only minor gap is no explicit mention of return format (e.g., JSON object), but the 'Read one clip' phrase implies a single response.

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 has 100% coverage with descriptions for all 5 parameters. The description goes far beyond the schema by explaining the exact effect of combinations (e.g., `select: [], render: {}` yields only a PNG), providing concrete examples, and describing the returned data shapes (element wrapper fields, type-specific data). This adds immense meaning.

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

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

The description clearly states 'Read one clip' with a specific verb and resource, and lists all the retrievable components (elements, voiceover, background, transition). It distinguishes itself by describing the `select` mechanism and the `render` parameter, which are unique to this tool and not present in sibling tools like `update_clips` 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?

The description provides explicit guidance on when to use this tool versus alternatives. It directly warns about the cost of 'repeated full reads' and explains how `select` can minimize context usage. It also hints at when to use sibling tools like `update_clips` (for transitions) and `update_elements` (for element edits) by describing the return format, enabling the agent to decide to read before editing.

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=true and destructiveHint=false, so the description does not need to reiterate those. It adds significant behavioral context beyond annotations: it explains that calling the tool logs the clueprint as 'used' (fire-and-forget) for the recents list, and that binary files return presigned URLs. This excellent additional detail earns a high score; a 5 would require even more coverage, such as explicit mention of rate limits or size limits on responses.

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 clear sections for each include mode, uses bullet points for readability, and front-loads the key verb. Every sentence provides direct value; there is no fluff or repetition of schema fields. The bonus detail about usage logging is a single, concise sentence at the end.

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 (3 parameters, 1 required, 1 enum) and the absence of an output schema, the description does a good job explaining return formats (metadata vs. tree vs. files with presigned URLs). It covers side effects (usage logging) and best practices for large clueprints. However, it lacks details on pagination or limits for very large clueprints, and the 'all' mode could use more caution about performance. A 5 would address these edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds substantial meaning beyond the schema for the 'include' parameter by explaining the effect and best practices for each enum value (e.g., 'metadata + the full file tree' and 'binary as presigned GET URLs'). For 'file_paths', it reinforces the dependency on include='files'. This is useful enrichment, earning a 4; a 5 would require adding similarly rich context for all parameters, which is already done well but not exhaustive for 'clueprint_id'.

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

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

The description clearly states the tool fetches clueprint data and uses a specific verb ('Fetch') along with the resource ('clueprint data'). It thoroughly distinguishes the various include modes, making it very clear what each call returns, which differentiates it from siblings like 'create_clueprint' or 'update_clueprint'.

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

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

The description provides explicit guidance on when to use each include mode, e.g., 'Call include="tree" first when exploring an unfamiliar clueprint' and 'use sparingly on large clueprints' for 'all'. It tells the agent exactly how to decide between modes, though it does not explicitly mention when not to use the tool, but the guidance is so clear that exclusions are implied. No alternative sibling tool is named for similar operations, but the tool itself covers many use cases.

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 declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds value by explaining that the tool provides 'general craft' guidance and describes what the guide covers (concept, typography, color, etc.), which gives the agent a clear expectation of the content. It's nearly perfect; a slight deduction because it doesn't explicitly state that the tool returns a textual guide or that no side effects occur, though these are implied 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 short sentences, each earning its place: first states what it is, second gives usage conditions, third clarifies scope. No redundancy, no filler. It's perfectly sized for the task.

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 has no parameters, clear annotations, and a simple retrieval purpose, the description fully covers what an agent needs: what the tool does, when to use it, and what content it covers. The sibling tool list is long and varied, so the clear usage guidance is essential for disambiguation. The description is complete and leaves no obvious gaps.

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

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

The input schema has zero parameters with 100% coverage, so the baseline is 3. The description adds value by implicitly explaining the scope of the returned content (the 'house style' covering specific design aspects), which helps the agent understand what to expect even though no parameters are needed. The score is elevated because the description compensates for the lack of parameter context by detailing the content domains.

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 retrieves 'Clueso's house style for composing video clips' and specifies the domains it covers ('concept, typography, color, composition, motion, and pacing'). It also distinguishes itself from other tools by clarifying it's for general craft guidance, not clueprint-specific, which helps differentiate from potentially sibling tools that might offer template-specific advice.

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 tells when to use this tool ('before composing or editing a clip's visuals when you're NOT following a clueprint, or to fill gaps a clueprint leaves silent'). This provides precise usage context, including both primary use case and a secondary fallback scenario, which effectively guides the agent's decision among the many 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's safety profile is covered. The description adds that it returns 'the JSON schema for an element type's type_data', which is useful behavioral context. However, it doesn't disclose details like response format, error behavior, or rate limits, which are not critical for a simple read-only tool.

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

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

The description is two sentences, both front-loaded with the primary action. Every sentence earns its place: the first states the purpose, the second provides usage guidance. No wasted words or redundancy.

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

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

For a tool with 2 parameters, no output schema, and no nested objects, the description is fully adequate. It explains the return value (JSON schema), the use case, and the relationship to sibling tools. An agent can confidently select and invoke this tool 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 coverage is 100% (both parameters fully described with enums and descriptions in the input schema). The description does not add additional meaning beyond what the schema provides. Baseline 3 is appropriate; the description does not need to compensate for missing schema info.

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 a JSON schema for an element type's type_data, with a specific verb ('Return') and resource ('JSON schema for element type's type_data'). It explicitly distinguishes from sibling tools 'add_elements' and 'update_elements' by positioning itself as a prerequisite call.

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

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

The description explicitly says 'Call this before add_elements / update_elements when you don't already know the field shape', providing clear context for when to use. It doesn't explicitly state when not to use (e.g., when schema is known) or list alternative tools, but the guidance is sufficient for most agents.

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 thoroughly discloses the output structure beyond what annotations provide: it lists canvas dimensions, per-clip summary fields (ids, indices, durations, element counts, voiceover_volume), and audio_tracks (with a detailed field list matching the add_audio shape). Since annotations already declare readOnlyHint=true and destructiveHint=false, the description adds rich behavioral context about the data format, which is critical given the absence of an output schema.

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

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

The description is a single paragraph of moderate length, front-loaded with the primary purpose. Every sentence adds value: the first sentence states the purpose, the second lists contents, and the third gives a usage example. It is clear and efficient, though slightly dense; breaking into bullet points could enhance readability, but it remains well-structured for an agent.

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 provides a comprehensive view of the return values (canvas, per-clip summary, audio_tracks with detailed fields). It also explains the relationship between audio_tracks and the add_audio input shape, which is essential for cross-project workflows. For a one-parameter read-only tool, this description is complete and leaves no ambiguity about what the tool returns.

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 has 100% coverage with a basic description for the single parameter 'project_id' ('The project ID'). The description does not add any additional semantic information about the parameter (e.g., format, constraints, or how to obtain it). With high schema coverage, the baseline is 3, and no extra value is provided by the description.

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 'Get a summary of a project' and enumerates the specific contents (canvas dimensions, per-clip summary, audio_tracks). This provides a precise verb+resource combination, and the detail distinguishes it from sibling get tools (e.g., get_clip, get_article) by specifying the project-level scope and the exact data returned.

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 advises when to call this tool: 'Call this to understand what's in the project before making changes.' It also provides a concrete workflow example for copying audio tracks to another project using add_audio. This gives clear context and implicit alternatives (e.g., use mutation tools after reading), meeting the criteria for explicit when-to-use 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?

The description adds significant behavioral detail beyond the annotations: clips are placeholders that become video only after processing, deleting one loses that scene, article placeholders are inserted into plainDoc, and jobs are sent to AVS. There is no contradiction with the readOnlyHint=false or destructiveHint=false 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 and front-loaded: the core action appears first, followed by placeholder semantics, prerequisites, and fallback behavior. Each sentence provides distinct information without filler.

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

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

For a complex asynchronous tool with no output schema, the description covers the core action, side effects, prerequisites, and alternative path well. The main gap is that it never states the return value or response shape, though the recording_session_id parameter and AVS references indirectly signal async behavior.

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

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

The schema already provides 100% parameter coverage with rich explanations, so the description is not required to repeat parameter details. It does not add parameter-specific meaning, but no extra compensation is needed given the 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 states a precise action: 'Create a screen-recording clip in a project,' and further clarifies the pipeline by mentioning blank placeholder clips, job entities, and AVS submission. It also distinguishes itself from the manual path (upload_file, then add_clips) so an agent can tell it apart from sibling tools.

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

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

The description gives explicit when-to-use guidance: it requires the Auto-Recording add-on and per-workspace credentials, and clearly names the fallback for workspaces without it: 'upload_file, then add_clips(kind='video')'. This is a concrete decision rule rather than an implied usage.

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 (destructiveHint=true), the description reveals the index shift behavior, the restriction on removing the last clip, and the full concurrency conflict domain. This adds significant value and does not contradict any 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?

Three well-structured sentences: core purpose, index shift and multi-removal guidance, then concurrency warning. Every sentence adds unique information with no redundancy. Front-loaded with the primary 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?

Covers the effect (removal and shift), constraints (last clip), and concurrency. No output schema exists, but the description explains the behavior sufficiently. Lacks explicit error conditions (e.g., out-of-bounds index), but overall adequate for a straightforward removal tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by explaining the effect of clip_index (shifts down by 1) and the implication for multiple removals, which goes beyond the schema's 'Zero-based clip index to remove.' This is useful behavioral 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 clearly states 'Remove a clip from the project by index' with a specific constraint 'Cannot remove the last remaining clip.' This distinguishes it from sibling tools like 'remove_elements' (which removes elements, not clips) and other project-level mutations.

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

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

Provides explicit when-to-use guidance: the last clip cannot be removed, and for multiple removals it advises 'remove from highest index to lowest' or capture IDs. Also gives clear concurrency instructions: serialize all mutations on the same project_id, do not run in parallel with any other mutation on the same project.

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

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

Annotations already declare destructiveHint=true. The description adds significant behavioral context: conflict domain is individual element, batch lands in one save, per-guide lock, and explicit concurrency constraints with whole-clip mutations. This goes well 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?

The description is concise with two distinct paragraphs: purpose then concurrency/alternatives. Every sentence adds unique value. No redundant or verbose phrases.

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 2 parameters, no output schema, and concurrency considerations, the description covers purpose, parameter structure, behavioral details, concurrency rules, and alternative tools. It is fully sufficient for an agent to use correctly, despite not describing return values explicitly.

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 both parameters. The description restates the structure of removals entries but adds no new meaning beyond the schema. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states 'Remove many elements across one or more clips' with specific verb and resource. It distinguishes from siblings like remove_clip (whole clip) and remove_from_project (audio tracks) by explicitly mentioning the alternative for audio removal.

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

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

Provides explicit when-to-use (removing elements), concurrency advice (parallel-safe for different elements, avoid whole-clip/whole-project mutations), and a clear alternative: 'To remove an audio track, use remove_from_project(target='audio')'. This fully covers usage context 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?

Annotations already mark destructiveHint=true and readOnlyHint=false, so the mutation nature is clear. The description adds valuable concurrency details (element-scoped vs whole-project mutation) and references the music_id source ('returned by add_audio'). While it doesn't discuss reversibility or error states, the concurrency guidance is a meaningful addition beyond annotations.

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

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

The description is well-structured with a brief introductory sentence followed by a bulleted list for target modes and a separate concurrency section. It is concise at ~100 words and front-loads the core purpose. The only minor issue is that the concurrency section could be slightly more compact, but overall it earns its space.

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

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

Given the tool's moderate complexity (two modes, conditional parameters) and no output schema, the description covers the essential use cases, parameter dependencies, and concurrency behavior. It could be improved by noting what happens on success (e.g., returns confirmation or updated project state) and error conditions (e.g., invalid element_id), but it is largely complete for an AI agent to use 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 value by clarifying the target-dependent parameter requirements (e.g., 'requires music_id — returned by add_audio') and explaining the relationship between target and conditional parameters, but the schema already describes each parameter's purpose adequately.

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 removes an element or audio track from a project, specifying two distinct targets ('element' and 'audio') with their required parameters. This distinguishes it from sibling tools like 'remove_clip' (which removes entire clips) and 'remove_elements' (which likely removes multiple elements at once).

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 explains when to use each target mode ('target=element' vs 'target=audio'), including the required parameters for each (clip_index+element_id vs music_id). It also provides concurrency guidance, telling the agent to serialize 'target=audio' mutations on the same project while noting element-scoped operations are parallel-safe with other element edits.

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 indicate readOnlyHint=false and destructiveHint=false, which is consistent with the mutating nature of reordering. The description adds valuable context: the handler rejects partial lists to prevent silent drops, and explains the z-index behavior. No additional behavioral traits (e.g., permissions, reversibility) are mentioned, but the core safety behavior is disclosed.

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

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

The description is only three sentences, all essential. It starts with the action, then explains the ordering, and ends with the critical usage constraint. No redundant or unnecessary 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?

The description covers the purpose, constraint, and prerequisite (get_clip). However, it does not mention the return value or any confirmation of success. Since there is no output schema, the agent would benefit from knowing what to expect after a successful reorder.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds the critical constraint that the handler rejects partial lists, which is not in the schema. This provides meaningful guidance beyond the parameter 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 'Reorder' and the resource 'elements inside a clip', and explains the z-index ordering semantics. It distinguishes itself from sibling tools like add_elements and remove_elements by focusing exclusively on reordering existing 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 explicitly instructs the agent to pass the full set of element IDs and warns that partial lists are rejected. It also directs the agent to get the current list via get_clip, providing a clear prerequisite. However, it does not explicitly state when not to use this tool or list alternative tools beyond get_clip.

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 show destructiveHint=false and readOnlyHint=false, so the agent knows it is a mutation that is not destructive. The description adds that it affects every clip, is case-insensitive on name, and lists common engines, which provides useful behavioral context beyond annotations.

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

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

The description is concise with three short sentences, each serving a distinct purpose: stating the action, providing usage context, and listing examples. There is no wasted text, and key 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 simplicity (3 required parameters, no output schema), the description is mostly complete. It could briefly mention the return value or confirmation behavior, but the context signals indicate low complexity, so the description suffices.

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 descriptions for each parameter. The description adds value by clarifying that voice_name lookup is case-insensitive and by listing common engine examples, but these are enhancements rather than necessities since the schema already documents the parameters adequately.

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 sets the voiceover voice for every clip in a project. It distinguishes between applying a clueprint's voice and switching all clips to a specific voice, differentiating it from sibling tools like voiceover_batch or update_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 use cases: applying a clueprint's voice or switching all clips to a specific voice. It gives guidance on how to read voice data from clueprints, but does not explicitly state when not to use it (e.g., for individual clip voice changes) compared to alternatives like update_clips.

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 (which only indicate mutation and non-destructiveness) by detailing key behaviors: ID assignment for left/right clips, element duplication across the split point, proportional voiceover splitting, and runtime validation of split_time. This fully compensates for the lack of annotation depth.

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 remarkably efficient: the first paragraph covers all core functionality, and the second paragraph provides essential concurrency constraints. No redundant sentences or filler words; every sentence 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?

Given the tool's complexity (affecting clips, elements, transcripts) and the absence of an output schema, the description is complete. It covers validation, side effects, ID behavior, and concurrency. An agent receives sufficient information to execute the tool correctly without needing external 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?

Although schema coverage is 100%, the description adds significant value by explaining that split_time is clip-relative and by specifying the rejection range (>0.1s and < clip_duration-0.1s). It also elaborates on the ID and element effects, 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 uses a specific verb-resource pair ('Split a video clip') and details the behavioral outcome (IDs, element duplication, voiceover splitting). It clearly distinguishes from sibling tools like 'duplicate_clip' and 'remove_clip' by specifying the split mechanics.

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 the tool's purpose and provides concurrency guidance ('Do not run it in parallel with ANY other mutation'). While it doesn't name alternative tools for non-split operations, the context of splitting is unambiguous and the serialization advice is actionable.

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 non-destructive and not read-only. The description adds that the switch is for the session, which is useful context. However, it does not disclose potential side effects, authorization needs, or error handling 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?

Two concise sentences with no wasted words. The first sentence states the purpose, and the second provides actionable guidance. Well 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 tool with one parameter and no output schema, the description is mostly complete. It could mention the return value (e.g., confirmation or workspace object) but is sufficient for an agent to understand usage.

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 provides 100% coverage with a clear description for the workspaceId parameter. The description does not add significant meaning beyond the schema, so a baseline score 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 tool's action: 'Switch the active workspace for this session.' It uses a specific verb and resource, and it is distinct from sibling tools like 'find' and 'create_project'.

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

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

The description guides the agent to use 'find(type='workspaces')' to list available workspace IDs, which is helpful. However, it does not explicitly state when not to use this tool or contrast with alternatives.

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 important behaviors: screenshots kept in markdown are retained, those removed are deleted, and order in markdown defines final order. The annotations already indicate mutability (readOnlyHint: false) and no destruction (destructiveHint: false), so the description adds valuable context beyond just 'update'.

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

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

The description is very concise with no wasted words. All four sentences provide essential information: purpose, screenshot placeholder syntax, screenshot lifecycle, and the recommended workflow. Information is front-loaded well.

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 lack of output schema and moderate complexity (2 params, one with placeholder syntax), the description covers the core function and screenshot behavior. It could mention what happens if markdown is invalid or provide example usage, but it is reasonably complete.

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

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

Schema description coverage is 100% (both parameters described), so baseline is 3. The description adds meaning by explaining the markdown parameter includes <SCREENSHOT {id}> placeholders and their behavior, which goes beyond the schema's generic description. This extra context justifies a 4.

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

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

The description clearly states the tool updates article text content from markdown and describes the use of <SCREENSHOT {id}> placeholders. It lacks explicit differentiation from siblings like add_article_media or update_article_media, but the purpose is specific enough.

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

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

The description provides a clear workflow: get the article first, modify the markdown, then call this. It does not explicitly specify when not to use this tool versus alternatives, but the workflow guidance is helpful.

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 that render=true is read-only, and that deletions are handled by a sibling tool via markdown. It explains the server-side pruning behavior. Annotations declare readOnlyHint=false and destructiveHint=false, which are consistent. The description adds valuable context beyond annotations, such as the deletion workflow and the tool's non-destructive update nature.

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 short, well-structured paragraphs. Each sentence serves a purpose: first states purpose, second gives usage bullets, third explains deletion via sibling. No fluff or repetition. Information is front-loaded and scannable.

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

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

Given no output schema and complex parameters (nested objects), the description covers most scenarios: update, inspect, and how to delete (via sibling). It mentions that render=true returns 'current details and a PNG preview', but does not specify what happens upon update (return value). Slightly incomplete for the update path, but overall well-rounded.

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?

Input schema has 100% description coverage, providing baseline of 3. The description adds guidance on how parameters interact: 'Provide one or more of zoom_factor, crop, shapes to change metadata' and 'Pass render=true (with no other updates) to fetch current details.' This clarifies usage patterns beyond the schema, earning a 4.

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

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

The description clearly states 'Update an article image/GIF (screenshot), or inspect its current state.' It specifies the resource (article media) and actions (update metadata, inspect state). It distinguishes from sibling tools like add_article_media and update_article by explicitly stating the deletion mechanism via update_article.

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: use render=true for inspection without mutation; provide one or more of zoom_factor, crop, shapes for updates. It directly tells the agent when NOT to use this tool (for deletion) and names the alternative (update_article). This is exemplary guidance.

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

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

Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false (no destruction). The description adds the partial-update behavior ('Only fields you pass are changed; omitted fields are preserved'), which is useful. However, it does not discuss side effects, idempotency, or permission requirements, so it adds moderate but not deep behavioral context beyond the annotations.

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

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

The description is concise, with two short paragraphs. The first sentence immediately states purpose. The rest efficiently explains how to get the id, the partial-update nature, and the deletion alternative. No unnecessary words 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?

Given the tool has 10 parameters, no output schema, and no nested objects, the description covers essential context: how to obtain the id (via get_project), that updates are partial, and the alternative for deletion. It does not explain error handling or validation, but for a mutable tool with good sibling references and schema, it is fairly complete.

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

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

Schema description coverage is 100% – all 10 parameters have individual descriptions in the input schema. The description lists a few examples (volume, fades, timing, loop) but adds no new semantic meaning beyond what the schema already provides. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Mutate fields on an existing music/SFX track by id.' It uses a specific verb ('mutate') and resource ('audio track'), and the mention of flipping knobs like volume, fades, timing, loop distinguishes it from sibling tools like add_audio (adding new tracks) and remove_from_project (deleting tracks).

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: read existing tracks via get_project.audio_tracks to get the id and current shape, then use this tool to update specific fields. It also clearly directs to use remove_from_project(target='audio') for deletion, a key alternative. It does not explicitly mention when to use add_audio instead, but the context is strong enough for an agent to differentiate.

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 destructiveHint annotation. It explains that all property updates land in one save, position moves apply first before property patches, video_styling is for video clips only, and voiceover_volume=0 mutes narration without deleting it. No contradiction with annotations (destructiveHint: true is consistent with mutation).

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

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

The description is well-structured with bulleted sections for each parameter. It is lengthy but every sentence earns its place given the complexity of the tool. The front-loading of the purpose and '[Always batch]' immediately orients the reader. Slightly verbose in explaining transition directions, but that is relevant detail.

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

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

The description covers all parameters, provides edge-case handling (voiceover mute, background vs background_color), concurrency constraints, and ordering dependencies. With no output schema, the description adequately fills any gaps about what the tool does (it updates and presumably returns the project or success). The complexity of the input schema (nested objects for transition, video_styling) is thoroughly explained.

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?

Despite 100% schema coverage, the description adds substantial value beyond the schema. For transition, it clarifies that transitions play at the END of the clip. For position, it explains move ordering and recommends separate calls. For voiceover_volume, it details the mute behavior and restoration. For background_color vs background, it distinguishes between color change and full replacement. This significantly aids correct invocation.

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 updates one or more clips in a single call and enumerates all updatable fields (background, transition, duration, title, visibility, position, voiceover_volume, video_styling). It distinguishes itself from sibling tools like remove_clip or add_clips by emphasizing batch operation and specific property scope.

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

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

The description provides explicit when-to-use guidance: 'Always batch' suggests using this tool even for single clip updates. It includes concurrency rules ('parallel-safe per clip', 'do NOT run concurrently with element/voiceover edits on the SAME clip or whole-project mutations') and ordering advice ('run update_clips BEFORE add_audio when adding audio + resizing clips'). This is exceptional guidance for selecting this tool over alternatives.

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 indicate destructiveHint=true and the description confirms destructive behavior by explaining file overwrites and deletions. It adds valuable behavioral context (patch semantics for metadata, file mutation types) beyond the annotations. Slightly missing details on reversibility but sufficient.

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

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

The description is concise, using bullet points for file mutations and clear sentences for metadata patch behavior. Every sentence adds value, and the structure front-loads the main purpose while organizing details logically. 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?

The description comprehensively covers input semantics and behavioral expectations for a mutation tool. It lacks explicit output/return value information, but given no output schema and the tool's nature (update idempotency), the agent can infer success from errors. Minor gap for 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?

Despite 100% schema coverage, the description adds significant value by grouping parameters (metadata vs files), explaining file mutation patterns with concrete examples (write text, binary, from URL, delete), and clarifying the use of 'content: null' for deletion. This is a substantial improvement over 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 explicitly states 'Update a clueprint's metadata and/or file contents in one call', using a specific verb and resource. It distinguishes itself from siblings like 'create_clueprint' and 'get_clueprint' by detailing the combined metadata patch and file mutation operations.

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

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

The description provides clear guidance on when to use the tool (e.g., metadata patch, file writes, deletes) and how to use different file mutation formats (inline, base64, URL). It lacks explicit mention of when not to use it or alternative tools for specific scenarios, but the context is adequate.

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 extensively discloses behavioral traits beyond the destructiveHint annotation. It explains partial success, grouping effects on z-order and coordinates, concurrency safety with per-element locking, keyframe replacement behavior (only specified tracks replaced, null/empty clears all), and fit_to_lines automatic sizing. These details are not in the annotations and are critical for correct 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 clear sections (batch, grouping, customizing, concurrency, keyframes, text elements) and front-loaded with the core purpose. It is longer due to necessary details, but every sentence adds value. Minor improvement could be tighter phrasing in some areas, but overall it is efficient.

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 (multiple element types, grouping, keyframes, concurrency, text-specific features), the description covers most essential aspects. It explains partial success, return of component_id for save_as_component, concurrency constraints, and references get_element_schema for type_data. Missing: explicit specification of the response format or error handling, but the output schema is absent, so the description carries the burden 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 already has 100% coverage with clear descriptions for each parameter. The description adds contextual meaning, such as the batch nature of updates, group semantics (new group takes first member's slot), keyframes placement (sibling of x/y, not inside type_data), and fit_to_lines behavior. This goes beyond the schema, though the schema itself is already strong.

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 updates many elements across clips in a single call, explicitly distinguishing it from a previous per-element tool and implying its batch nature. The verb 'update' and resource 'elements' are specific, and the contrast with sibling tools like add_elements and remove_elements is evident.

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 guidance: it replaces the per-element tool (always batch), advises against concurrency with whole-clip/whole-project mutations on the same guide, and references get_element_schema for type_data fields. It also specifies when to use fit_to_lines for text elements. However, it does not explicitly compare to alternative update tools (e.g., reorder_elements) beyond the batch nature, which keeps it from a top score.

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?

Disclosed beyond annotations: partial update (only provided fields change), aspect ratio conversion to canvas (1920×1080 fit), element coordinates reflow automatically, and whole-project mutation conflict domain. Annotations only provide readOnlyHint=false and destructiveHint=false, so description adds critical 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?

Well-structured with a summary sentence followed by parameter details and behavioral notes. Not overly verbose, though the aspect ratio examples could be shortened. Still efficiently communicates essential 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?

Given no output schema, the description covers expected behavior comprehensively: partial update, parameter semantics, effect on canvas and coordinates, concurrency constraints. No missing information 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 coverage is 100%, but description adds value: explains aspect ratio format with common examples and canvas sizing, clarifies folder_id empty string for root, and notes element coordinates are fractions that reflow. Slightly redundant with schema but enriches understanding.

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 'Update a project's metadata' and lists specific operations (rename, change description, move to folder, change aspect ratio). It distinguishes from sibling tools like create_project, duplicate_project, and get_project by focusing on modifications.

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 when to use: 'Only fields you provide are changed' and how to move to root with empty string. Provides concurrency rules: 'Do not run it in parallel with ANY other mutation on the same project_id' and allows parallel mutations on different projects.

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 are readOnlyHint=false (write operation) and destructiveHint=false, which align with the description. The description goes far beyond annotations by detailing the upload flow: file_name returns a curl command that the agent/user must execute, the PUT targets the base domain (not cloud storage), and the hosted mode returns a token requiring a subsequent call to check_uploads. It also explains behavioral constraints like 'one call issues one upload_token' and that hosted uploads can handle multiple files. No contradictions.

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

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

The description is well-structured with a numbered list and bold headings for each mode. It is front-loaded with the three-mode summary. However, it is somewhat verbose—the final paragraph repeating how mcp_upload_id is used in other tools is partially redundant with the earlier usage guidance. Every sentence is valuable, but some consolidation could improve conciseness. Still, it is clear and easy to scan.

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

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

Given the tool's complexity (three modes, 4 parameters, no output schema, many sibling tools), the description is remarkably complete. It covers the full upload flow, explains how to handle the returned identifiers, and integrates with downstream tools. It also addresses potential client limitations (e.g., desktop vs browser). The description leaves no significant gaps for an AI agent to misunderstand.

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 significant value beyond the schema by explaining the three modes and how parameters interact (e.g., file_name vs file_names vs request_hosted_upload). It also clarifies the implications of each parameter (e.g., file_names is 'shown on the upload page as guidance'). The description enriches the agent's understanding of parameter semantics, justifying a score above 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 tool's purpose: uploading files to Clueso. It explicitly defines three distinct modes (file_name, file_url, request_hosted_upload), each with a specific use case and resource. The description also explains how the returned mcp_upload_id integrates with sibling tools like add_elements, add_audio, and add_clips, making the tool's role in the ecosystem unambiguous.

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

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

The description provides explicit guidance on when to use each mode. For file_name, it says 'Prefer this whenever there's no human at a browser.' For file_url, 'Use when the file is already on the open web.' For request_hosted_upload, 'use ONLY when a human should pick files in a browser.' It also explains when not to use the UI mode (no shell/no PUT capability) and directs to check_uploads afterward. This is exemplary usage 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 annotations (destructiveHint=true), the description reveals critical behavioral details: async TTS generation, one-save-batch behavior, retiming side effects that reset clip duration and cut elements, and concurrency conflict domain. 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 summary, bulleted action list, an important warning block, and concurrency guidance. Every section earns its place given the tool's complexity. It is 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?

Given the tool's complexity (batch, three actions, async, side effects, concurrency), the description covers almost all aspects. Minor gap: the return value ('one result object per input entry') lacks detail on structure, but no output schema is provided. Still, the description is highly informative.

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%, baseline is 3. The description adds value by explaining entry ordering, async nature of generate_speech, and the relationship between clip_index and clip_id across actions. It also clarifies the effect of set_and_generate combining both steps. This surpasses baseline but does not add structural details 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 'Set voiceover text and/or trigger speech generation for any number of clips in a single call,' specifying the verb (set/trigger), resource (voiceover scripts for clips), and unique batch capability. It differentiates the three action types explicitly, distinguishing from any single-clip tools like set_voice.

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 when to use each action, including ordering ('Entries within one call are applied in order'), concurrency rules ('parallel-safe' for different clips, serial for same clip), and explicit warnings about not running alongside whole-clip/project mutations. It also advises when to use estimate_duration or generate speech early to avoid timing issues.

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