Clipform

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

Annotations provide little behavioral info (all false). The description adds context on insertion position and refers to clipform_create_form for config schemas, but does not disclose effects on form logic or permissions. Adequate but lacks 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?

Three concise sentences, front-loaded with main action. Every sentence provides essential information without 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?

Without an output schema, the description should explain return values (e.g., new node ID). It does not. It adequately covers insertion behavior and references create_form, but omits post-operation results, leaving gaps for a creation 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 detailed descriptions. The description adds value by explaining default insertion and referencing create_form for config details, going beyond the schema to clarify usage.

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 node to an existing form, using a specific verb ('Add') and resource ('new node to an existing form'). It distinguishes from siblings like update_node and delete_node by focusing on creation, and mentions insertion position control via 'after_node_id'.

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 default insertion behavior (before end screen) and how to control position, which guides when to use this tool. However, it does not explicitly contrast with alternatives like clipform_update_node, though the purpose 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 already indicate safe, read-only, idempotent behavior. Description adds 'Returns output URL' and 'Typical render time 10-60 seconds', enhancing transparency without contradiction.

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

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

Three concise sentences, front-loaded with purpose, zero redundancy. Every sentence adds 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?

Provides sufficient context for a status-check tool: purpose, parameter usage, expected output (URL), and timing. Could mention polling or error states but still adequate.

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

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

Schema covers both parameters fully. Description reinforces batch usage ('one call instead of one per job') and adds timing context, adding value beyond 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?

Clearly states the resource ('render jobs') and action ('check status'), and explicitly links to two specific sibling tools that initiate these jobs, distinguishing its role.

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

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

Provides clear usage context: check after render start, batch via job_ids or single via job_id. Lacks explicit when-not-to-use or alternatives, but sufficient for correct invocation.

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

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

Discloses creation behavior, return values, and anonymous claim URL. Annotations already indicate non-read-only and non-idempotent. 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?

Well-organized with upfront summary, detailed node specs, and example. Slightly verbose but efficiently packed with 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?

Covers all node types, config defaults, return values, and cross-reference to guide. Output schema exists, and description adequately conveys the creation outcome.

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 extensive detail: node type roles, config defaults, option constraints, AI-PROTECTED note, color formats, and an example. Greatly extends 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's goal: 'Create a new Clipform (interactive video-style form)' and specifies the return values. It distinguishes creation from update/delete/get siblings.

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

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

Provides context for authenticated vs. anonymous sessions, and mentions when to use clipform_get_guide for craft guidance. Does not explicitly list when to use alternatives like clipform_update_form.

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 'This cannot be undone' and details the confirmation requirement, adding value beyond the annotation. No contradiction.

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

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

The description is two concise sentences that front-load the critical information. No wasted words.

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

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

Given the destructive nature and no output schema, the description covers the essential behavioral aspects. It could mention what happens on success (e.g., returns confirmation), but the schema and annotations are adequate.

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

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

Schema coverage is 100%, so the schema already provides detailed parameter descriptions. The tool description does not add extra parameter meaning beyond what's in the schema, meeting the baseline.

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

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

The description clearly states 'Permanently delete a form and all its nodes' with specific verb and resource. It distinguishes from sibling tools like clipform_delete_node and clipform_update_form.

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 specifies 'Requires user confirmation before it runs' and the confirm parameter description provides guidance on when to set it. While it doesn't explicitly mention alternatives, the context implies usage for deletion only.

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 provides behavioral details beyond the annotations: destructive action (confirmed by destructiveHint: true), automatic re-linking, and the need for user confirmation. This adds useful context not present in the structured annotations.

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

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

The description is three concise sentences with no unnecessary words. The main action is stated first, followed by important behavior details and constraints.

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 lack of an output schema, the description covers the essential outcomes (deletion, re-linking, what cannot be deleted). It provides enough context for an agent to understand the tool's effect and limitations.

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?

All three parameters have descriptions in the schema, but the description adds extra semantic guidance, such as when to set 'confirm' to true and how 'form_id' differs from the share_id. This enhances 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 clearly states the action ('Delete a node from a form') and adds specific details like automatic re-linking and constraints (cannot delete start node or last end screen). This distinguishes it from sibling tools like clipform_delete_form or clipform_delete_node_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?

The description mentions that user confirmation is required and that certain nodes cannot be deleted. It gives context for when to use the tool, but does not explicitly contrast with alternatives. However, the constraints are clear enough for an agent to decide appropriately.

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

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

Annotations already mark destructiveHint=true, and the description adds behavioral details: 'Requires user confirmation' and 'cleans up external resources (Mux video asset, storage file).' This provides transparency about the tool's side effects beyond the annotation.

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

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

The description is two sentences, front-loaded with the core action, and contains zero fluff. Every sentence adds necessary information.

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

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

With 3 well-documented parameters and a destructiveHint annotation, the description covers the essential aspects: action, resource cleanup, and confirmation requirement. No output schema exists, but for a deletion tool this is acceptable. Slightly incomplete regarding what happens after deletion (e.g., no return value), but adequate for the tool's complexity.

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

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

Schema description coverage is 100% with detailed descriptions for all three parameters. The tool description adds no additional semantic value beyond what the schema provides, 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 explicitly states 'Remove media from a node' with a specific verb and resource. It details cleanup of external resources (Mux video asset, storage file), which distinguishes it from sibling tools like clipform_delete_node (deletes node itself) and clipform_upload_node_media (uploads).

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

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

The description clearly instructs that user confirmation is required before execution, and the confirm parameter schema elaborates on how to handle confirmation. However, it does not explicitly mention when not to use this tool compared to alternatives like clipform_delete_node, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds useful context about returned GeoJSON being simplified and ready for Map, and explains mainlandOnly behavior with examples, enhancing trust 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 clear sentences plus a separate line for mainlandOnly. Every sentence adds value, no redundancy.

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

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

Without output schema, description adequately explains return format (simplified GeoJSON) and use case. For a read-only fetch tool, this is complete and sufficient for correct agent 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 covers 100% parameters with descriptions. Description adds practical examples for mainlandOnly (Corsica, Hawaii), providing extra clarity beyond 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?

Title and description clearly state the verb 'Fetch' and resource 'GeoJSON boundary polygon' for country, city, or region. Distinguishes from sibling CRUD tools by being a pure read operation.

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

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

Description provides context (for Map composition 'boundary' prop) but does not explicitly compare to alternatives or state when not to use. Guidance is implied but not structured.

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 all false (readOnlyHint, etc.), so the description carries the burden. It discloses that the tool generates audio and returns a URL and word-level captions, processes up to 10 items in parallel, and requires tone and voice parameters. This sufficiently describes behavior beyond what annotations provide, without contradiction.

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

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

The description is concise and well-structured, with dedicated sections for purpose, usage, voice recommendations, tone guidance, and batch limits. Every sentence is informative and earns its place, avoiding 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?

Given the tool has no output schema, the description compensates by stating it 'Returns audio URL and word-level captions per item.' It also clarifies the parameter `items` can be 1-10 objects and runs in parallel. Annotations are sparse, but the description provides sufficient context 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?

Schema description coverage is 100%, but the description adds substantial value beyond the schema: it explains use cases, voice selection tips (e.g., 'a London quiz gets ryan or sonia'), tone guidance ('Energetic and playful for quizzes'), and batch processing behavior. This enriches the agent's understanding of how to set parameters effectively.

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: 'Generate narration audio from text with word-level captions.' It provides specific use cases like quiz narration and form instructions, distinguishing it from sibling tools that deal with forms, nodes, or media management. The verb 'generate' and resource 'TTS' are precise.

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 the tool: 'Use this for quiz question narration, survey introductions, form instructions, or any node that benefits from a human voice.' It proactively suggests narration for quizzes and content-rich forms. Although it doesn't mention when not to use or alternatives, the context is clear and no sibling tool offers TTS, so no exclusion is needed.

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 no safety hints (all false), so description carries full burden. It discloses output format (9:16, 720x1280), Ken Burns effects, transitions, public URL return, duration behavior, rendering time estimates (15-120 seconds), and parallel rendering advice. 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?

Description is well-structured: front-loaded with main purpose, then items detail, then advanced usage. Every sentence adds value without redundancy. Length is appropriate for a complex tool with 12 parameters.

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

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

No output schema, but description explains the return value (public URL). Covers format, duration, rendering time, integration with other tools, and advanced patterns. Complete for a tool of this complexity given the rich input schema.

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

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

Schema description coverage is 92%, so baseline is 3. The description adds value by explaining the high-level purpose of parameters like items (type image/video and their behavior), duotone (desaturation + mapping), texture (print-style overlay), and the wait parameter strategy. It provides context not in schema, like parallel rendering and timing.

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 a video from images and/or video clips synced to audio, with specific use cases (narrated question backgrounds, topic visualizations). It distinguishes from siblings like clipform_generate_tts (narrated audio) and clipform_search_media (royalty-free images).

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 (video generation for form nodes) and when-not (e.g., multi-question builds should use wait: false and poll clipform_check_render). Suggests combining with clipform_generate_tts and clipform_search_media, and gives parallel rendering strategy.

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, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds context that nodes are returned in sequential order, which is additional behavioral detail. 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 two sentences with no extraneous information. It front-loads the purpose and then lists return contents concisely.

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 get operation with one parameter and no output schema, the description adequately covers what the tool returns. It could mention error conditions (e.g., form not found) but is otherwise sufficient.

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

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

The input schema provides a detailed description for form_id (UUID, not share_id). The description does not add further meaning to the parameter beyond what the schema already conveys, so it meets the baseline for 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 specifies the verb 'retrieve' and the resource 'form's details', and distinguishes it from siblings like clipform_list_forms (which lists forms without details) by mentioning it returns nodes in sequential order, title, settings, options, config, and media status.

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

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

The description implies usage for fetching a specific form's details but does not explicitly state when to use this tool over alternatives (e.g., clipform_get_guide, clipform_get_workflow) or when not to use it. No exclusions or prerequisites are provided.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns markdown, does not return a workflow, and details quiz variant behavior. No contradictions. Additional context like alias processing and variant-only-for-quiz is provided.

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: core purpose, a negative statement to avoid misuse, then a list of types and aliases, and finally variant details. Each sentence provides essential information without redundancy. Efficiently packed with value.

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

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

For a tool with 2 parameters and no output schema, the description is fully complete. It explains inputs (including aliases and variant conditions) and outputs (markdown with specific sections). It also references the sibling tool when appropriate, leaving no gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: lists all types with aliases, explains the optional variant parameter is only for quiz, and describes the effect of different variants. This goes well 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 it retrieves craft knowledge for building a specific form type, lists what is returned (question psychology, difficulty curves, etc.), and explicitly distinguishes what it does NOT return (step-by-step workflow). This differentiates it clearly from sibling tool clipform_get_workflow.

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

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

Explicitly says when to use (get craft knowledge) and when not to use (if need step-by-step workflow, use clipform_get_workflow). Provides a comprehensive list of accepted types and aliases, giving precise guidance on input 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by mentioning 'including processing status', which is useful 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?

Two sentences, no wasted words, front-loaded with the main action and a practical use case.

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 tool with two required params and good annotations, the description is complete enough. It mentions processing status, which is key context. No output schema exists, but the purpose is clear.

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

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

The schema has 100% coverage for both parameters (form_id, node_id). The description does not add extra meaning beyond what the schema already describes, so 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 clearly states the verb 'get' and resource 'media attached to a node', and adds the use case of checking processing status. This distinguishes it from sibling tools like clipform_delete_node_media or clipform_upload_node_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?

The description provides context 'useful for checking if a video upload has finished processing', implying when to use it. It does not explicitly list when not to use or alternatives, but the sibling set includes upload and delete tools, so differentiation is implied.

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, idempotentHint, and destructiveHint, and the description is fully consistent—it describes a read-only retrieval operation. The description adds valuable context about what is not returned (craft knowledge) and the structure of the output (build recipe components), going beyond annotations to clarify scope.

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

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

The description is front-loaded with the core purpose and well-structured with clear sections (exclusions, aliases, variant info, parameter groups). While lengthy, every sentence serves a purpose given the tool's complexity. Minor redundancy (e.g., repeating type lists) could be tightened, but overall it's 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?

The description provides a high-level overview of the output (build recipe components) but lacks details on exact return structure, error handling, or examples. Given no output schema, more specificity (e.g., sample output or expected format) would enhance completeness. Still, the parameter grouping and usage notes cover essential context for invocation.

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

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

With 100% schema coverage, the baseline is 3. The description adds significant extra value by grouping parameters by form type, indicating defaults (e.g., question_count default 8), and explaining variant-specific behavior. This reduces cognitive load for the agent, justifying a higher score.

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

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

The description clearly states it retrieves a step-by-step build workflow for a specific form type, listing what it returns (tool sequence, settings, etc.) and what it does not (craft knowledge). It differentiates from sibling clipform_get_guide and provides type aliases, making the purpose unambiguous.

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

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

The description explicitly directs users to clipform_get_guide for craft knowledge, providing a clear exclusion. It also lists type aliases and variant-specific parameters, guiding context-appropriate usage. However, it does not explicitly contrast with other siblings like clipform_get_form, leaving some ambiguity about when to use this versus retrieving a form directly.

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, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds no further behavioral details like pagination, ordering, or limits, but the annotations cover the key safety aspects adequately.

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

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

A single, well-structured sentence that conveys the essential purpose without any extraneous words. It is front-loaded and 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?

For a simple read-only listing tool with one parameter and sufficient annotations, the description is complete enough. It could optionally mention return format, but the lack of an output schema and the tool's simplicity make this acceptable.

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 clear description for the 'type' parameter including enum values and default. The tool description does not add new information about parameters beyond the schema, so it meets the baseline.

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

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

The description clearly specifies the tool's action ('list') and the resource ('available creative assets') with concrete examples ('sound effects, animations, fonts') for a video composition context. It distinguishes from siblings like clipform_search_media which searches over a broader 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?

No explicit guidance on when to use this tool versus alternatives such as clipform_search_media or clipform_get_node_media. The description does not mention prerequisites, intended use cases, or when to avoid this tool.

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

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

Annotations already provide safety profile (readOnlyHint, idempotentHint, not destructive). Description adds that it returns props schemas, which is useful 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?

Three sentences, front-loaded with purpose, followed by usage guidance and sibling distinction. Every sentence adds value with no waste.

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

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

Fully explains purpose, returns (props schemas), and usage relation to other tools. No gaps given the tool's simplicity.

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

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

No parameters exist, so schema coverage is 100% by default. The baseline of 4 is appropriate as description correctly omits parameter detail.

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 'browse' and resource 'video compositions and their expected props schemas'. It clearly distinguishes from sibling tools like clipform_render_composition and clipform_generate_video.

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 to call this before clipform_render_composition and directs to clipform_generate_video for narrated slideshows, providing clear usage context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: pagination is cursor-based, next_cursor is included when more results exist. This provides useful 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?

Two sentences with no wasted words. Front-loaded with the core purpose 'List forms...'. Every sentence adds value.

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

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

The description covers the main functionality (list with filtering and pagination). However, it lacks details about the return structure (e.g., array of forms). Given no output schema, this is a minor gap. Still, it's adequate for a list tool with optional filters.

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 each parameter described. The description adds meaning by explaining pagination mechanism (cursor-based) and that next_cursor indicates more results, which is beyond schema definitions.

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

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

The description clearly states the verb 'List' and the resource 'forms', and distinguishes from sibling tools like clipform_get_form which retrieves a single form. It also specifies the scope: 'in your workspace'.

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 mentions optional filtering and pagination, implying when to use this tool for listing with filters. It does not explicitly state when not to use or provide alternatives, but the context is clear given sibling tool names.

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 basic read/write info (readOnlyHint=false). The description confirms a write operation but adds no extra behavioral details like idempotency, side effects, or prerequisites. Minimal value 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, front-loaded with the main action, no redundancy. Every word is informative and earns its place.

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

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

For a simple logging tool with no output schema, the description covers the basic purpose. However, it lacks context about when to call this tool (e.g., after form creation) and any prerequisites, making it moderately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'sources and image attributions' which map to the details object, but doesn't add meaning beyond the schema's field descriptions.

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

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

The description clearly states it saves an audit trail for a generated form, specifying the verb 'Save' and resource 'audit trail.' It distinguishes from sibling tools like clipform_create_form or clipform_update_form by focusing on recording attribution and sources.

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

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

No guidance on when to use this tool versus alternatives. For instance, it doesn't specify that it should be called after form generation or that it's not for other logging purposes.

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 behavioral traits beyond annotations: strict validation of inputProps (unknown/missing props fail with schema in error), precision rounding for Map compositions at low zoom, parallel batch processing, return behavior (public URL or job ID). Annotations are minimal (readOnlyHint=false), so description carries full burden and does so excellently.

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: first sentence defines purpose, second clarifies alternatives, third covers batch vs single mode in clear bullet-like paragraphs. Every sentence earns its place; no filler.

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

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

The description covers all aspects needed for correct usage: available compositions (via clipform_list_compositions), output formats, single vs batch modes, wait behavior, strict validation, and return value (URL or job ID). Despite no output schema, the return behavior is clearly described.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaningful context beyond schema: strict validation behavior, the zoom rounding note for compositionId inputProps, and the wait parameter's blocking vs fire-and-poll distinction. This elevates from baseline 3 to 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 it renders specialized video compositions to MP4 or PNG, and distinguishes from clipform_generate_video (for narrated slideshows). The verb 'render' and resource 'video composition' are specific, and the mention of alternatives differentiates from siblings.

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

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

Explicitly states when to use (for custom animations, geography, motion graphics that clipform_generate_video can't provide) and when not to (for narrated slideshows, use clipform_generate_video). Also covers batch mode vs single render and discusses wait behavior.

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

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

Discloses that all results are pre-cleared for commercial use, which is critical context beyond annotations. No contradiction with readOnlyHint or idempotentHint.

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: first sentence states purpose, then usage guidance, then example. Slightly long but every sentence earns its place. Could trim a bit.

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 could mention return format. However, it is a search tool whose results feed into other tools, and the input usage is fully covered. Adequate for the complexity.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds an example with multiple queries, clarifies orientation default (portrait), and explains count defaults per kind, adding value.

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

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

Clearly states it searches images or stock video clips, distinguishing it from siblings like clipform_search_music and clipform_search_news. Also mentions batching multiple queries.

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 how results feed into clipform_generate_video or upload via clipform_upload_node_media. Suggests using alt text for selection. Lacks explicit 'when not to use' but context is strong.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the agent knows it's safe and idempotent. The description adds useful behavioral context: returns download URLs, duration, artist, license info, and integration with other tools, exceeding annotation coverage.

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, each adding value: first states purpose, second gives usage context, third explains output and next steps. Front-loaded and no wasted words.

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

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

Given 6 parameters and no output schema, the description covers output details and integration. It lacks pagination info but the count parameter addresses max results. Adequately complete for a search tool.

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

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

Schema description coverage is 100%, so all parameters are documented. The description only adds general usage context (quiz forms) but does not enhance parameter meaning further. 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 clearly states the tool searches for royalty-free music tracks and ambient sounds, specifying the resource and action. It distinguishes from sibling tools like clipform_search_media and clipform_search_news by focusing on music and ambient sounds.

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 specific usage context (quiz forms, surveys, longer forms) and tells how to use the output (pass URL to video/slideshow tools). However, it lacks explicit 'when not to use' or alternatives, missing full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context: fallback behavior, coverage 'post-May-2025', exclusions (timeless topics), and data sources (NewsAPI, The Guardian). 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?

Three concise sentences covering purpose, coverage, and return fields. No redundancy, front-loaded with critical info.

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 annotations and full schema coverage, description covers return fields, coverage boundaries, and use-case context. No output schema exists, so explaining returned fields 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 coverage is 100%, baseline 3. Description adds value by stating 'Max results per provider (default 5)', clarifying that count is per provider, not total, which is not evident from 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 it is a 'Fallback news lookup for clients without native web search' and specifies it 'Returns structured current-news articles', making the purpose explicit and distinct from siblings like clipform_search_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 states when to use: 'for clients without native web search', and when not: 'Narrower and less current than native web search tools (WebSearch, web fetch) when available', providing clear 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 that only linear routing is supported and that conditional branching is a planned feature, adding context beyond annotations. Annotations indicate idempotentHint: true, which is not contradicted.

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 no redundant sentences. It front-loads the core purpose and follows with necessary details and an example, earning its place efficiently.

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

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

For a tool with no output schema and moderate complexity, the description covers the essential behavioral aspects (routing types, default rules, future feature) adequately. A slight gap is the lack of explanation about rule ordering or conflicts, but overall 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining default rules, rule structure, and providing an example, which helps the agent understand parameter usage beyond schema definitions.

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

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

The description clearly states the tool sets routing logic on nodes, distinguishes it from sibling tools like clipform_update_node, and provides a specific verb-resource pairing.

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 advises using one call for multiple nodes instead of separate calls, and explicitly warns against using conditional branching as it is not yet supported. It lacks explicit alternatives or when-not-to-use, but 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?

Description explains partial update behavior (only sends provided fields) and highlights AI-PROTECTED restrictions, adding value beyond annotations which already indicate idempotentHint: true. No contradiction.

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

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

Two clear, front-loaded sentences that state purpose and key behavior without waste.

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

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

With no output schema, the description should indicate what the tool returns (e.g., updated form object) but omits this. Parameter details are covered, but overall completeness is adequate but lacks return value information.

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 parameters are well-documented in schema. Description adds context about partial updates and AI-PROTECTED restrictions, enhancing understanding beyond 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?

Clearly states verb 'Update' and resource 'form', and lists specific aspects (title, publish status, settings, tags). Distinguishes from sibling tools like clipform_create_form and clipform_delete_form.

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 guidance on partial updates and AI-PROTECTED parameters, but does not explicitly state when to use this tool versus alternatives (e.g., when to update vs. create or get). Usage context is implied, not direct.

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 behavioral context beyond annotations: it states that node positions remain unchanged, and that config defaults apply when omitted. It also references the config source (@vid-master/config). The annotation already indicates idempotency, so the description complements without contradiction.

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

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

The description is five sentences, each adding essential information: purpose, batching advice, node ID sources, positional behavior, and config schema origin. No redundant content exists, though it could be slightly more compact.

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 (array of update objects), the description covers key aspects: batching, ID sources, and non-destructive position behavior. However, it omits details on error handling (e.g., invalid node IDs) and does not indicate the return format, leaving some gaps for agent confidence.

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 detailed descriptions. The description adds value by clarifying that form_id is a UUID (not a share_id), that options replacement is all-or-nothing, and that updates are batched. These insights improve parameter 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 clearly states the verb 'Update' and the resource 'nodes', specifying what can be updated (text, type, config, options). It distinguishes from siblings by noting that it does not change node positions, contrasting with operations like add or delete. The purpose is specific and unambiguous.

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

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

The description provides context for when to use the tool: updating existing nodes. It advises batching multiple updates in one call, specifies required node IDs and their sources, and mentions that config schemas are external. It does not explicitly exclude alternatives like add_node for new nodes, but the context is clear enough for an 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?

The description discloses key behavioral traits: sequential upload, automatic fetching for public URLs, processing paths (Mux for video, Supabase for image), and the role of captions for per-word highlighting. These go beyond the annotations which only declare non-readOnly and non-destructive.

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

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

The description is concise and front-loaded: it states the main action first, then constraints, then details. Every sentence adds value without redundancy or unnecessary 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?

Given the moderate complexity (2 required params, nested objects) and absence of output schema, the description covers all essential aspects: main functionality, constraints, specific use-case instructions, and integration with other tools (clipform_generate_tts, clipform_render_composition, clipform_generate_video).

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 good descriptions. The description adds extra context for two parameters: captions (from clipform_generate_tts) and fit_media (advice for renders). This adds meaningful value 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 clearly states 'Upload media for one or more nodes' with specific constraints (max 10, sequential upload). It distinguishes this tool from siblings that delete, get, or add nodes, as no other sibling tool performs media upload.

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 usage context: applicable node types (choice, open, scale, binary, button) and specific guidance for when to set fit_media:true (renders). However, it does not explicitly mention when not to use this tool or list 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 already declare readOnly/read-only. Description adds return values (transcript, title, channel, duration) and failure cases. 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?

Two short paragraphs, front-loaded with main purpose. Every sentence adds value—no 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?

Despite no output schema, description fully explains what is returned. Covers limitations, supported URL formats, and defaults. Complete for this simple extraction 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 covers 100% of parameters with descriptions. Description does not add extra meaning or usage details beyond what schema provides, so 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?

Description clearly states action: 'Extract the transcript, title, and channel info'. Specific verb+resource, and distinct from all sibling tools (none are transcript-related).

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 NOT to use: private/age-restricted videos, disabled captions, non-YouTube URLs. Provides clear context, but does not name alternative tools (though no relevant siblings exist).

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