Clipform

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

Annotations indicate non-readOnly and non-destructive. The description adds value by explaining insertion behavior (default before end screen, controllable via after_node_id). 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 efficient sentences: first states core purpose, second adds insertion details and references. No wasted words, front-loaded with key 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 parameters, nested objects, and an output schema, the description covers the essential usage (insertion behavior, node type reference). It could mention more about the output, but the output schema exists to compensate.

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

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

Schema coverage is 100%, and the schema provides detailed descriptions for each parameter. The description adds minimal extra meaning beyond referencing clipform_create_form for node types/configs, which is useful but not essential beyond the schema.

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

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

The description clearly states the action ('Add'), the resource ('new node'), and the context ('to an existing form'). It also mentions insertion position and type matching, which distinguishes it from sibling tools like clipform_update_node and clipform_delete_node.

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 default insertion behavior and how to control position with after_node_id, but does not explicitly mention when not to use this tool or contrast it with alternative tools beyond the sibling 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?

The description adds valuable behavioral context beyond annotations: sequential attachment, reusability of media assets, and node type restrictions. Annotations already show non-destructive and non-read-only; 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?

Five focused sentences with zero waste. Front-loaded with the core action and constraints. Every sentence adds distinct 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 fully covers the tool's operation given its complexity (2 params, no nested objects). It addresses reuse, limitations, and integration with other tools. Output schema exists, so return values need not be detailed.

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 extra meaning (e.g., sequential behavior, fit_media advice for renders, max 10 items) that enhances the schema's parameter documentation.

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 attaches a media asset to one or more nodes with constraints (max 10, sequential, specific node types). It distinguishes from siblings like clipform_upload_media_asset (upload step) and clipform_delete_node_media (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?

Explicitly says to use after clipform_upload_media_asset and lists supported node types. Does not explicitly state when to avoid using or alternative tools for different operations, but context is sufficient.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds typical render time, auto-attach behavior, and output URL disclosure, complementing well 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?

Five concise sentences, front-loaded with purpose, no wasted words. Every sentence delivers meaningful 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 status checking, batch capability, output URL, auto-attach outcome. With output schema present, no gaps remain for this polling 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 adds crucial context on batch vs single usage and the behavior of job_ids vs job_id, enhancing 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 explicitly states 'Check the status of render jobs' and names the specific tools that start the renders, clearly distinguishing its purpose 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?

Provides clear guidance on using job_ids for batch checks vs job_id for single, and mentions automatic attach obviating polling. Does not explicitly exclude other uses, but is sufficient.

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 idempotentHint=true, destructiveHint=false. Description adds that API verifies object landed before flipping state, which is useful behavioral context. No contradictions. Could mention idempotency explicitly but annotations cover that.

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 serving a purpose: action, verification step, and exclusion for video. Front-loaded with main purpose. No redundant text.

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

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

Given output schema exists and schema covers parameter fully, description adequately explains the tool's purpose, when to use, and key behavioral detail (storage verification). Complete for this simple 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 has 100% coverage with description for media_asset_id. Description adds that it's the id from clipform_upload_media_asset, which provides helpful context beyond the schema's basic 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?

Clearly states it confirms a signed-PUT still image upload finished, specifying the resource ('still image') and the action ('confirm upload'). Distinguishes from video uploads which settle automatically.

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 call ('right after PUT succeeds'), consequence of not calling ('asset stays invisible'), and when not needed ('video uploads'). Provides 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 indicate a non-read-only, non-idempotent operation, and the description adds meaningful behavioral context: returns viewer URL/form ID, lands in the user's workspace for authenticated MCP clients, and offers a claim URL for anonymous sessions. It does not cover failure modes or permission requirements, but adds substantial value 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 long but well-structured with clear headings for node types, defaults, and an example. It front-loads the core purpose and outputs before systematically detailing each node type. No redundant sentences; every part serves to inform the 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?

For a complex creation tool, the description covers output behavior, all seven node types, their configurations, defaults, and points to clipform_get_guide for additional guidance. The schema and output schema fill remaining gaps, making the overall definition complete.

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

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

The input schema covers parameters generically (e.g., `config` is a free-form object), but the description provides exhaustive per-node-type configuration keys, defaults, and constraints. The example further clarifies how to structure a form, adding significant 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 explicitly states 'Create a new Clipform' and specifies the resource type ('interactive video-style form') and the outputs (viewer URL and form ID). This clearly identifies the action and resource, distinguishing it from siblings like 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 provides context on when to use the tool (to create a form) and explains the difference between authenticated and anonymous sessions. It also points to clipform_get_guide for config crafting, but it does not explicitly mention when not to use this tool versus related tools 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 mark destructiveHint=true, but the description adds valuable behavioral context: it moves to trash (not permanent deletion), stops accepting responses immediately, and can be restored later. This goes beyond annotations and clarifies the real impact.

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

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

The description is three concise sentences, front-loaded with the main action. Each sentence adds essential information: what happens, immediate effect, and confirm requirement. 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?

With the annotations, input schema, and this description, the agent has a complete picture: destructive action, trash semantics, restorability, confirmation requirement, and parameter details. No output schema exists, so return value explanation isn't necessary. The description is sufficient for safe and 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 input schema already provides 100% parameter coverage, including the UUID format, the distinction from share_id, and the confirm flag semantics. The description doesn't add new parameter-level details beyond what the schema states, so the 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 states a specific action ('Move a form and all its nodes to the trash') and clearly identifies the resource (form plus its nodes). It distinguishes from sibling tools like clipform_delete_node by focusing on the whole form, not a single node.

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

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

The description clearly implies when to use the tool: to delete/trash an entire form. It mentions immediate cessation of responses and restorability, which helps the agent decide. It doesn't explicitly name alternatives like clipform_delete_node, but the context is clear enough with siblings 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?

Annotations already mark it as destructive, but description adds important behavioral details: automatic re-linking, node deletion constraints, and user confirmation requirement, exceeding the annotation information.

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

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

Two concise sentences immediately present the action, constraints, and requirement, with 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?

Covers all essential aspects for a destructive node deletion tool: purpose, auto-re-linking, limitations, and confirmation prerequisite. No return value needed without output schema.

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

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

Schema description coverage is 100%, and the description does not add new semantic information beyond what the schema already provides for each parameter.

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 the action ('Delete a node from a form'), specifies automatic re-linking, and distinguishes from siblings like clipform_delete_form or clipform_delete_node_media by naming the resource and 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?

Explicitly lists what cannot be deleted (start node, last end screen) and requires user confirmation, but does not directly compare with alternative tools like clipform_update_node.

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 valuable behavioral context beyond the annotations: it specifies that deletion includes cleaning up external resources (Mux video asset, storage file), which the destructiveHint annotation does not detail. It also reiterates the need for user confirmation. No contradiction with annotations (destructiveHint: true is consistent).

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 primary action and followed by a secondary detail. Every part is meaningful and no extra words. Excellent 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?

The tool has no output schema and is destructive with specific side effects. The description covers the main action, resource cleanup, and confirmation requirement. It does not mention return value or post-conditions, but these are acceptable gaps. For a delete tool, it provides sufficient context for safe 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?

Schema description coverage is 100%, so the schema already documents all three parameters fully. The description's mention of 'confirmation' aligns with the confirm parameter, but it does not add new meaning beyond what the schema's confirm description already provides. 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 removes media from a node, specifying the exact actions: delete the media record and clean up external resources (Mux video asset, storage file). This distinguishes it from sibling tools like clipform_delete_node (which deletes the entire node) and clipform_attach_node_media (which adds 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 'Requires user confirmation before it runs,' which guides the user on the need for confirmation. However, it does not explicitly state when to use this tool versus alternatives (e.g., clipform_delete_node for deleting the whole node or clipform_get_node_media for viewing). The confirm parameter in the schema further reinforces the guideline, but the description itself lacks exclusion 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safety. The description adds behavioral context by explaining the mainlandOnly parameter's effect (excluding islands/overseas territories) and providing concrete examples (Corsica, Hawaii), which goes beyond annotation information.

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

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

The description is extremely concise with two sentences. The first sentence covers purpose and output, and the second explains a key parameter. No unnecessary words or repetition, making it efficient and 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 no output schema, the description appropriately characterizes the return format as 'simplified GeoJSON' and its application. It covers the primary parameter effectively. Minor omission: does not specify if the result is a Feature or FeatureCollection, but overall sufficient for 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?

Schema coverage is 100% with descriptions for all parameters. The description enriches parameter understanding by adding specific examples for mainlandOnly, offering context not present in the schema's default description. This adds value beyond 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 clearly states the verb 'Fetch' and the resource 'boundary polygon' for geographic entities. It specifies the output format as 'simplified GeoJSON' and its intended use in a Map composition, distinguishing it from sibling tools which focus on media, forms, or nodes.

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 use for obtaining geographic boundaries for map compositions but does not explicitly state when to use this tool versus alternatives or when not to use it. No guidance on exclusions or prerequisites is 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?

Discloses parallel processing for multiple items, return of audio URL and word-level captions, and gives examples of tone usage. Annotations already show readOnlyHint=false and destructiveHint=false, so description adds moderate behavioral context (parallel execution, output format) 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?

Description is front-loaded with purpose, then logically flows through usage suggestion, voice selection, tone parameter, and logistics (max items, returns). Every sentence adds distinct value; no filler or repetition.

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

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

Covers all key aspects: purpose, when-to-use, how to pick voices/tone, parallelism, max items, and output. Output schema exists so return details are partly covered. Missing only minor details like character limits (already in schema), but overall complete for effective tool 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 coverage is 100%, but description enriches each parameter: explains voice options with personality descriptors ('British male, clear'), gives concrete tone examples per form type, and details the items array's parallel execution. Adds significant meaning beyond schema descriptions.

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

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

Description clearly states 'Generate narration audio from text with word-level captions' and lists specific use cases (quiz narration, survey intros, etc.), distinguishing it from siblings like clipform_generate_video or 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?

Provides explicit when-to-use guidance ('Proactively suggest narration for quizzes and content-rich forms'), voice selection rules, tone parameter advice, and constraints (max 10 items, never mix voices). Lacks explicit when-not-to-use but is otherwise thorough.

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 non-readOnly and non-destructive. The description richly discloses behavior: 9:16 output, Ken Burns effects, immediate vs async returns, auto-attachment to form nodes, and URL retrieval process.

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 front-loaded purpose, followed by details and usage guidance. Minor redundancy (wait described in both description and schema) but overall efficient 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 15 parameters, high schema coverage, and output schema present, the description covers all key aspects: parallel rendering, auto-attachment, sibling disambiguation, and workflow integration. 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 93%, so baseline is 3. The description adds value by explaining parameter relationships (e.g., duotone with halftone texture, captions from clipform_generate_tts) and workflow context (e.g., node_id skips manual steps).

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 generates a video from images/video clips synced to audio, and explicitly distinguishes from sibling tools like clipform_render_video_template and clipform_render_composition, with specific use cases.

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

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

Provides explicit guidance on when to use this tool vs alternatives, including disambiguation between narrated vs silent montages, and instructions for multi-render parallelization with wait: false.

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, so the description's addition of 'sequential order' for nodes and explicit return of title, settings, options, config, and media status adds useful 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 extremely concise: two sentences covering purpose and return value with zero fluff. Every sentence adds value.

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

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

Given the output schema exists (though not shown) and the tool is a simple read operation with clear annotations, the description is complete enough for an agent to understand what the tool does and what it 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 clear description for form_id ('The form UUID... not the short share_id'). The description does not add any additional parameter semantics 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 action (retrieve a form's details) and the specific resource (form) along with what is included (all nodes in sequential order). This distinguishes it from sibling tools like clipform_list_forms and clipform_get_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 implies usage when full form details are needed, but it does not explicitly state when to use this tool versus alternatives like clipform_list_forms for a summary or clipform_get_node_media for individual node media. No when-not-to-use guidance is 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 mark the tool as readOnlyHint and destructiveHint false. The description adds behavioral context by stating it returns markdown and details the content areas (question psychology, difficulty curves, etc.). 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 concise and well-structured. It leads with the primary purpose, immediately clarifies what is not returned, then enumerates types and aliases in a clear list. Every sentence adds necessary 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?

Given the tool's simplicity (2 parameters, no output schema), the description is fully complete. It describes the return content in enough detail for an AI to understand what will be retrieved and how to specify parameters 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%, providing a baseline of 3. The description adds value by listing accepted aliases for the 'type' parameter and clarifying that 'variant' is only for quiz. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool retrieves 'craft knowledge for building a specific form type' and lists exactly what it returns (question psychology, difficulty curves, etc.). It also explicitly distinguishes itself from the sibling tool clipform_get_workflow by stating what it does NOT return, ensuring 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 provides explicit guidance on when to use this tool versus the alternative clipform_get_workflow: 'Does NOT return a step-by-step build workflow - use clipform_get_workflow for that.' It also lists all valid form types and their accepted aliases, making parameter selection straightforward.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with that. It adds behavioral context by mentioning 'processing status', which is not covered by annotations. 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 sentences with no fluff. Every word contributes to understanding the tool's purpose and usage.

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, annotations, schema coverage, and presence of an output schema, the description provides everything an agent needs to decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, so the schema documents both parameters adequately. The description adds value by indicating the return includes processing status, which complements the schema's 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 tool retrieves media attached to a node, including processing status, and provides a specific use case (checking video upload completion). It distinguishes itself from sibling tools like clipform_attach_node_media or clipform_upload_media_asset.

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 a clear use case ('useful for checking if a video upload has finished processing'), indicating when to use it. It does not explicitly state when not to use it or mention alternatives, but the context 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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns a build recipe with specific components (tool sequence, settings, etc.) and does not return craft knowledge. 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?

Description is well-organized: main purpose first, then exclusions, then type listing, aliases, and per-type args. Slightly long but each section serves a 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 18 parameters (mostly optional) and no output schema, the description thoroughly explains parameter usage per type, return content, and variant handling. Complete for a complex 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 all parameters (100% coverage). Description adds value by grouping parameters per form type, listing aliases, and explaining optionality, making it easier to choose correct parameters.

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 tool retrieves a step-by-step build workflow, lists all form types and aliases, and explicitly contrasts with clipform_get_guide. This distinguishes it from siblings.

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

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

Explains when to use (getting build workflow), when not (for craft knowledge), and provides optional parameters grouped by form type, guiding the agent on correct combinations.

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, and destructiveHint=false. The description adds context about the specific asset types returned (sfx, animation, font), which aligns with the read-only nature. 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?

Single-sentence description with no wasted words. It is front-loaded with the main action and resource, making it 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 simple parameter (one optional enum), annotations covering safety, and presence of an output schema, the description is fully sufficient. No missing critical 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% with a clear description for the 'type' parameter. The tool description reiterates the asset types in human-readable form, adding marginal value beyond the schema's own 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 the verb 'List' and the resource 'creative assets' with specific examples (sound effects, animations, fonts). It distinguishes itself from sibling tools like clipform_search_media by focusing on asset types for video compositions.

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 like clipform_search_media or sibling tools. The description implies usage for listing assets by type but does not discuss when to choose one tool over another.

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 readOnly, idempotent, non-destructive. The description adds that the tool returns 'expected props schemas' and helps 'discover visual styles', providing 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, perfectly concise, no wasted words, and 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 zero parameters, an output schema exists, and sibling tools are present, the description is complete: it covers purpose, usage context, and alternatives. No gaps remain for an agent to understand when and how to use the 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?

The input schema has zero parameters with 100% coverage, so baseline is 3. The description does not add parameter details, but none are needed since there are no parameters.

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 lists available video compositions with their props schemas, using the verb 'browse' and specifying the resource. It distinguishes itself by mentioning it should be called before clipform_render_composition and differentiating clipform_generate_video for narrated slideshows.

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 'Call this before using clipform_render_composition' to discover visual styles and input props, and provides an alternative tool for narrated slideshows. This gives clear when-to-use and when-not-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?

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description adds valuable behavioral context about pagination (cursor-based, next_cursor included). This goes beyond annotations without contradicting them.

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

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

The description is two sentences, front-loading the main purpose and then adding pagination details. Every sentence is necessary and without 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 presence of an output schema and high schema coverage, the description adequately covers the tool's behavior. It mentions pagination, which is not in the schema, but could optionally list supported filters. It is sufficient for an agent to understand the core functionality.

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 only mentions 'optional filtering' and pagination, adding no extra semantics beyond what the schema provides for individual parameters.

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 lists forms with optional filtering. The verb 'List' and resource 'forms' are specific, and the scope 'in your workspace' adds context. However, it does not explicitly differentiate from sibling listing tools like list_assets or list_compositions, though the resource name helps.

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 is provided on when to use this tool versus alternatives (e.g., get_form for a single form) or when not to use it. The description only implies usage through optional filtering but offers no explicit 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 declare readOnlyHint, destructiveHint, and idempotentHint. Description adds context about template selection and controls exposure, but does not contradict annotations.

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

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

Two sentences with zero waste, front-loaded with purpose, and clear structure.

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

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

Output schema exists, so return format is covered. Description completes the context by linking to render tool and alternative composition approach.

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 in schema, so description adds value by explaining what the tool returns (template names and controls) beyond the empty input 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?

Description uses specific verb 'Browse' and resource 'video templates', defines them as curated Scene arrangements, and distinguishes from sibling clipform_render_composition for custom layer stacks.

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 before clipform_render_video_template and provides alternative for fully custom layer stacks via clipform_render_composition.

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 show non-read-only and non-destructive hints; the description confirms a write operation ('save'). However, it does not disclose side effects like whether the operation is idempotent or whether it overwrites existing logs. The description adds modest 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 filler: first sentence states the action, second clarifies the content. Every sentence earns its place, and the description 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 three required parameters with nested objects and no output schema, the description suffices to explain the tool's purpose and the data needed (sources and attributions). It could mention that the operation is safe to call multiple times, but completeness is already high.

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 provides a high-level purpose ('records sources and image attributions') but does not add critical details beyond 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?

The description clearly states the tool saves an audit trail for a generated form, specifying it records sources and image attributions. The verb 'save' and resource 'audit trail' are explicit, and the purpose is distinct from sibling tools like create_form or 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 implies usage after form generation to log provenance, but it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it or any prerequisites.

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 minimal hints (readOnlyHint=false, destructiveHint=false), so the description carries full burden. It discloses mutation (creates URL/job ID), synchronous vs. async behavior, strict validation of inputProps (error on unknown props), map precision rounding at wide zoom, parallel batch execution, and automatic node attachment. 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 relatively long but well-structured, front-loading the core purpose and alternatives. It efficiently covers multiple scenarios (single, batch, attachment) with clear sections. Some repetition (e.g., output formats mentioned twice) but each sentence adds value.

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

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

Given 8 parameters with 100% schema coverage and an output schema (implied), the description covers all key aspects: usage scenarios, batch behavior, node attachment, error handling, and comparisons with sibling tools. No obvious gaps for an experienced agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: it explains the wait parameter's effect, the purpose of items for batch, node_id/form_id for auto-attachment, captions for TTS, and specific inputProps behavior (map zoom precision). It also clarifies relationships between parameters in single vs. batch mode.

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 'Render a specialised video composition to MP4 or PNG' and contrasts with clipform_generate_video, clearly distinguishing its purpose from siblings. It also directs to clipform_list_compositions for available compositions, making the tool's role 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 detailed when-to-use guidance, including explicit alternatives: use clipform_generate_video for narrated slideshows, clipform_render_video_template for form/quiz beats, and this tool only when neither fits. It also explains batch vs. single usage, auto-attachment to nodes, and warns against polling or manual chaining.

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 mutation (readOnlyHint false, destructiveHint false). Description adds context: renders through Scene composition, auto-attaches to node if node_id provided, and warns against polling or manual chaining. No contradictions, but could mention idempotency or rate limits.

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 separate paragraphs for purpose, comparison, and usage flow. Each sentence adds value. Slightly long but not wasteful; could be trimmed slightly.

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 output schema exists (context signals), the description fully covers behavior, parameters, workflow, and sibling differentiation. It explains the auto-attachment mechanism and when to skip manual steps, leaving no gaps for an agent.

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

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

All 7 parameters have schema descriptions (100% coverage). The description adds value by explaining controls are template-specific and that captions are carried onto attached media. It also clarifies wait behavior. Schema already documents well, so slight bonus for extra 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 it renders a curated video template to MP4 or PNG from a controls object, contrasting with hand-assembling layers. It distinguishes from siblings like clipform_generate_video and clipform_render_composition, making the purpose unmistakable.

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 advises when to use this tool (form/quiz beats) versus alternatives (narrated montage, custom composition) and instructs to call clipform_list_video_templates first. Provides 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?

Discloses key traits beyond annotations: results are pre-cleared for commercial use, include descriptions for selection. Annotations already cover safety (readOnly, idempotent, non-destructive), and this description adds relevant behavioral context without contradiction.

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

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

Front-loaded with purpose, then usage guidance, then concrete example. Every sentence adds value with no redundancy. Efficient and well-structured.

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 presence of output schema, description appropriately covers input parameters, use cases, and result quality (commercial use, descriptions). Complements sibling tools and provides sufficient context 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%, so baseline is 3. Description adds value by explaining that multiple queries run in one call (not separate), and clarifies max queries (10) and orientation default (9:16 frame). Example demonstrates usage of count and orientation.

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 for images or stock video clips, with specific verb 'search' and resource 'media'. Distinguishes from sibling tools like search_music and search_news.

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 context: use results for clipform_generate_video or upload workflow. Mentions multiple queries per call for efficiency. Lacks explicit when-not-to-use or exclusion conditions but still highly informative.

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 read-only and idempotent behavior. The description adds that it returns download URLs, duration, artist, and license info, which aligns with annotations and provides useful output details. 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 concise at 4 sentences, front-loading the purpose, then use-case, then integration, then output. Every sentence earns its place with no redundancy.

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

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

Given the output schema exists and the description already covers return types and integration with other tools, it provides complete context for an AI agent to understand when and how to use this tool effectively.

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 documentation covers all 6 parameters (100% coverage), so baseline is 3. The description adds value with example queries for the 'query' parameter (e.g., 'upbeat quiz background'), enhancing understanding 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 searches for royalty-free music and ambient sounds, using specific verbs and resources. It distinguishes from siblings by focusing on music, and provides concrete use-case examples like quiz forms and surveys.

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 recommends when to use the tool (quiz forms, surveys, longer forms) and how to integrate results with other tools (clipform_generate_video, clipform_render_video_template). It lacks explicit 'when not to use' guidance, 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 already provide readOnlyHint, idempotentHint, destructiveHint. The description adds important behavioral context: sources (NewsAPI, The Guardian), coverage recency, and return fields. No contradiction with annotations.

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

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

Three concise paragraphs: purpose, coverage/limitations, and returned fields. Every sentence adds value; no fluff. Front-loaded with 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 output schema exists, description still provides complete context for tool use: purpose, when to use, coverage, return structure. No significant gaps.

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

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

Schema descriptions cover 100% of parameters. The description adds context about query scope (e.g., 'post-May-2025', example queries) and return fields, which aids parameter selection. Slight extra value above 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 'Fallback news lookup for clients without native web search' and specifies it 'Returns structured current-news articles from NewsAPI and The Guardian.' It differentiates from native web search tools (WebSearch, web fetch) and other sibling search tools (e.g., clipform_search_media, clipform_search_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 states it is a 'fallback' for clients without native web search, and that it is 'Narrower and less current than native web search tools (WebSearch, web fetch) when available.' Also defines coverage limits: 'recent events, people, and topics (post-May-2025)' and exclusions: 'Does NOT cover timeless topics.'

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 the idempotent nature (idempotentHint=true) and that conditional branching is unsupported, preventing misuse. Rules without option_content are explained as defaults. 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?

Concise, well-structured with an example and critical note. Every sentence adds value 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?

Covers purpose, usage, and limitations well. However, missing description of return value or success/failure indication, which would be helpful 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%, but the description adds value by explaining the rule structure and providing a concrete example that clarifies how array entries map to routing logic.

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 'Set routing logic' and resource 'nodes', clearly distinguishing from sibling tools like clipform_add_node or clipform_update_node. The example reinforces the purpose.

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

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

Explicitly advises batching multiple nodes in one call for efficiency and warns that conditional branching is a planned feature not to be used. No direct alternative tool is mentioned, 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 already indicate idempotentHint=true and destructiveHint=false. The description adds context about patch semantics and AI-PROTECTED parameters, but does not elaborate on mutation details, auth requirements, or side effects beyond what the schema provides. This is adequate but not rich.

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-loading the purpose and then the update behavior. Every word carries meaning with no redundancy. It is optimally concise.

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 15 parameters and no output schema, the description is brief. It covers high-level purpose and patch behavior but omits workflow context (e.g., typical usage sequence, effect of is_live on publishing). Adequate but could be more helpful for complex 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?

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal value beyond the schema, only noting AI-PROTECTED restrictions which are also in the schema descriptions. 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 it updates a form's title, publish status, settings, or tags. The verb 'update' and resource 'form' are explicit. While it doesn't explicitly differentiate from sibling update tools like clipform_update_node, the context of form fields makes it distinguishable.

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 partial update behavior ('Only sends fields that are provided - omitted fields remain unchanged') and hints at AI-PROTECTED parameter restrictions. However, it does not explicitly state when to use this tool versus alternatives like clipform_create_form or clipform_get_form, nor does it mention prerequisites like obtaining form_id.

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

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

Beyond annotations (which indicate it is not read-only and not destructive), the description discloses that node positions are unchanged and details config merging behavior, including replacement on type change and null deletion. This adds significant 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 a single focused paragraph, front-loaded with the main action, and every sentence adds necessary 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?

Given the complexity of updating multiple node fields and config merging, the description covers all necessary aspects. Since an output schema exists, no need to describe return format. All required parameters are addressed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining config merging details, options replacement, and source of node IDs, which is not fully captured in the schema descriptions.

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

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

The description clearly states it updates existing nodes' fields (text, type, config, options) and supports batch updates. It distinguishes from sibling tools like clipform_add_node (adds nodes) and clipform_delete_node (deletes nodes).

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

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

It advises using batch updates instead of separate calls and specifies that node IDs come from three related tools. It does not explicitly exclude usage scenarios but provides clear context for when to use this tool.

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

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

Discloses key behaviors beyond annotations: sequential upload, max 10, automatic fetching for URLs, different storage pipelines (Mux for video, Supabase for image), and the relationship with captions for highlighting. No annotation contradictions.

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

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

The description is four well-organized sentences with zero waste. Each sentence adds necessary context: purpose, workflow step, URL handling, and media-type-specific behavior.

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

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

Given the complexity (nested array, multiple media types, connection to other tools), the description is complete. It explains the workflow, constraints, and parameter implications without needing to describe the output schema since one exists.

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 significant value: it explains that captions should come from clipform_generate_tts, that ai_generated drives a disclosure chip, and that providing a URL triggers automatic fetching. This context goes beyond the schema descriptions.

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

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

The description clearly states the action: uploading one or more media files into the workspace media library. It specifies constraints (max 10, sequential) and distinguishes from sibling tools by positioning it as step one that requires follow-up with clipform_attach_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?

Explicitly tells when to use (upload media) and what to do after (attach to node). It also explains how captions from clipform_generate_tts enable per-word highlighting, providing context for when to use this tool in conjunction with others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about returning full transcript plus metadata and constraints (e.g., does not work for private videos). No contradictions, but the description reinforces the behavioral profile.

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 purpose and then provide limitations. Every sentence earns its place; no unnecessary 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 simple parameter set and no output schema, the description covers what the tool does, what it returns (transcript + metadata), and its limitations. However, it doesn't specify the exact output format (e.g., JSON structure), which would be helpful for invoking the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters. The tool description adds only marginal value beyond the schema (e.g., mentions return contents but not parameter-specific syntax). 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 specifies the verb 'Extract' and the resource 'transcript, title, and channel info from a YouTube video', making the purpose clear. It distinguishes itself from sibling tools which are unrelated (e.g., clipform_create_form, clipform_generate_video), so there's no confusion.

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

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

The description explicitly states when to use (public YouTube videos with captions enabled) and when not to (private/age-restricted, captions disabled, non-YouTube URLs). This provides clear usage context, which is sufficient since no sibling performs similar transcript extraction.

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