Clipform

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses a non-obvious side effect: inserting into a linear flow automatically re-links the chain so the prior node points to the new one. That is exactly the kind of behavioral detail annotations cannot convey.

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

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

Four short sentences, front-loaded with the action and default position, then the re-linking rule, then the logic exception. No filler or restatement of the name.

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 a nested node object with a 10-value type enum, an arbitrary config object, and an existing output schema, the description covers insertion semantics and offloads type-specific config to clipform_create_form plus guide references. It does not mention failure modes (e.g., invalid after_node_id, node limits), which keeps it just short of 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 the baseline is 3, but the description adds real meaning for after_node_id (omit to append before the end screen) and clarifies that node types and config schemas match clipform_create_form rather than being documented here. This lifts it above the schema-only 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 names a specific verb and resource ('Add a new node to an existing form') and immediately scopes behavior: default insertion is before the end screen, and after_node_id controls position. An agent can distinguish this from clipform_update_node or clipform_create_form without opening any schema.

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

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

It explicitly routes the agent away from a sibling: 'you do not need clipform_set_logic for a simple insert' but 'Branching still needs an explicit logic write.' It also points to clipform_create_form for node types and clipform_get_guide for craft guidance, giving clear when-to-use context.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the agent knows this mutates state safely-repeatedly. The description adds batching semantics (sequential application of multiple items) and asset reusability, but never says what happens to media already on a node (overwrite vs. append) or what a partial batch failure looks like — notable for a destructive mutation.

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

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

Four short sentences, front-loaded with the core action and the batching cap before the type restriction. No filler, though the closing reusability sentence is somewhat redundant with the opening 'existing workspace media asset'.

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?

An output schema exists, so return values need not be explained, and the description covers batching, type restrictions and reuse. However, for a tool flagged destructive it omits the most consequential behavior: whether attaching replaces existing node media, and what happens on failure partway through a sequential batch.

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%, including detailed guidance on fit_media and show_captions, so the schema carries the parameter burden. The description only restates the batch limit and reusability of media_asset_id, adding little beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb (attach), the exact resource (an existing workspace media asset produced by clipform_upload_media_asset), and the target (one or more nodes). It clearly separates itself from clipform_upload_media_asset, clipform_get_node_media and clipform_delete_node_media by naming the source of the asset and the direction of the 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?

Gives a real constraint: only node types that support media, enumerated explicitly (choice, open, scale, draw, binary, button), plus the batching rule (max 10, sequential). It does not name alternatives for the inverse operations (removing or reading node media), so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: typical render time of 10-60 seconds, and the non-obvious fact that attachment happens automatically when node_id was supplied and its outcome surfaces here. It stops short of, say, failure/error semantics for jobs that never complete.

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?

Four sentences, all load-bearing, ordered from what the tool does to how to call it to what comes back. The batching instruction and the attach-automation note are front-loaded where an agent will see them. Minimal overlap with the output schema beyond one short clause.

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 an output schema present, return values need not be re-explained, and the description wisely limits itself to one line about output URLs. Between the annotations, the output schema and this description, an agent has everything needed to call it correctly, including the timing expectation that prevents premature polling.

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 earns above baseline by explaining the semantic distinction the schema cannot: job_ids is a batching mechanism ('one line of status per job') rather than a plain array, and job_id vs job_ids are alternatives rather than combinable filters.

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

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

States a specific verb+resource ('Check the status of render jobs') and scopes it to jobs created by clipform_render_video_template or clipform_render_composition. This distinguishes it cleanly from siblings like clipform_get_results or clipform_get_node_media without needing to open any schema.

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

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

Explicitly routes the agent: use job_ids to check a batch in one call, job_id for a single job. It also resolves the implicit question of whether to poll, stating 'no need to poll to completion' because attach is automatic. Both the when and the when-not are covered.

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 non-read-only, idempotent, non-destructive, closed-world. The description adds genuinely new behavior: the server verifies the object landed in storage and flips the asset from processing to ready, and that skipping the call leaves the asset invisible. It does not discuss retry semantics despite the idempotentHint, or any auth/permission requirements, so it falls short of a 5.

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

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

Three sentences, front-loaded with the action, then the reason, then the exclusion. Every sentence carries distinct information; there is no restatement of the title or name.

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 an output schema present, return values need not be described. For a 3-parameter, two-required workflow tool the description supplies the prerequisite call, the timing constraint, the failure consequence and the video carve-out — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so media_asset_id, form_id and context are already documented in the schema, including the anonymous-session routing caveat for form_id. The description adds no parameter-level meaning (e.g. behavior when media_asset_id is unknown or already ready), so baseline 3 applies.

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

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

States a specific verb and resource — 'Confirm a signed-PUT still image upload finished' — and situates it in the workflow relative to the sibling clipform_upload_media_asset whose upload_url it consumes. An agent can distinguish it from clipform_upload_media_asset and clipform_attach_node_media without opening any schema.

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

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

Gives explicit when ('call this right after the PUT succeeds'), explicit consequence of omission ('the asset stays invisible in the library'), and an explicit when-not ('Not needed for video uploads (they settle automatically)'). This is the full when/when-not/alternative pattern.

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 and idempotentHint=true, but the description adds materially new behavior: this is a soft delete to trash that can be restored, responses stop being accepted immediately, user confirmation is required, and an authenticated session is mandatory. These are exactly the traits an agent needs before invoking a destructive tool.

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

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

Four short sentences with zero waste; the action and its reversibility are front-loaded, followed by the confirmation and auth requirements. Every sentence earns its place.

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

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

With rich annotations, full schema description coverage, and no output schema to explain, the description covers everything needed: what happens, reversibility, confirmation flow, and authentication gating. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, and the schema already explains confirm, context, and form_id in detail, including that form_id is the UUID rather than the share_id. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource (move a form and all its nodes to the trash), naming the scope that distinguishes it from clipform_delete_node, which targets a single node. The agent can tell the two siblings apart without opening either schema.

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

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

Gives clear context: requires explicit user confirmation, needs a signed-in account, and an anonymous session is redirected to sign-in. It does not explicitly name the alternative for deleting a single node, but the prerequisites and conditions for use are well specified.

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

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

Adds substantial behavior beyond the annotations: automatic re-linking of the logic chain, the protected start/last-end-screen nodes, and the deferred-effect behavior on live forms (node persists until publish). These are non-obvious side effects and constraints that directly affect safe invocation.

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

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

Four short sentences, each contributing a distinct constraint (effect, re-linking, protected nodes, live-form semantics, confirmation). Front-loaded with the core action and 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?

For a destructive mutation with no output schema, the description covers side effects, guardrails, confirmation requirements, and live-form behavior. Nothing an agent needs to call it correctly appears to be missing.

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

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

Schema description coverage is 100% with four documented parameters, so the schema already carries parameter meaning; the description adds no additional parameter detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Delete a node from a form'), and the affected resource is unambiguous among siblings named delete_node_media and delete_form. An agent can differentiate this from adjacent tools without inspecting the schema.

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

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

Gives concrete usage constraints: cannot delete the start node or the last end screen, and requires user confirmation before running. It doesn't name alternative tools (e.g., update_node to modify instead of remove), so it stops short of explicit alternatives, but the conditions are clearly actionable.

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

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

Beyond the destructiveHint/idempotentHint annotations, the description discloses precisely what gets destroyed versus preserved: the node link is removed while the media asset and files remain in the workspace library and continue working elsewhere. It also states a user-confirmation precondition, adding behavioral context annotations do not carry.

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 waste, and the critical contrast (unlink only, asset survives) is front-loaded before the confirmation requirement. Every clause carries distinct information.

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

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

For a destructive mutation with no output schema, the description covers the two things an agent most needs: what is and isn't destroyed, and that confirmation is required. Combined with annotations and 100% schema coverage, nothing material is missing.

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

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

Schema description coverage is 100%, with confirm, context, form_id and node_id all documented in the schema (including the confirm-after-explicit-approval rule and the UUID-vs-share_id distinction). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

"Remove media from a node by unlinking it" names a specific verb (remove/unlink) and resource (media on a node), and the clause about the asset staying in the library distinguishes this from sibling operations like clipform_delete_node or asset deletion. An agent can tell it apart from clipform_attach_node_media and clipform_get_node_media without opening any schema.

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

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

The scope clause (media detached, asset preserved, other nodes/forms unaffected) tells the agent the situation this tool is for, and it implicitly excludes destructive asset deletion. However, no sibling is named as an alternative and there is no explicit "use clipform_delete_node instead when..." routing, so it stops short of full when/when-not 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that the output is simplified GeoJSON and detailing how mainlandOnly affects the result with concrete examples (Corsica, Hawaii). It does not contradict 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: the first sentence communicates the core function and output usage, and the second clarifies a key parameter. No filler words; every sentence earns its place and the most important information is front-loaded.

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

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

With an output schema present, the description does not need to detail return values. It covers the tool's purpose, output format, and the key parameter behavior. Minor gap: the description lists 'country, city, or region' but omits 'state' from the schema enum, though the schema itself clarifies this. Overall adequate for an agent to select and call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning for mainlandOnly by giving examples of excluded islands, which goes beyond the schema's generic 'Keep only the largest landmass' phrasing. It also implies the effect of simplification in the first sentence, supplementing maxPoints.

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

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

The description uses a specific verb ('Fetch') and resource ('GeoJSON boundary polygon'), and immediately states the output's purpose ('ready to use as the boundary prop in the Map composition'). It clearly distinguishes the tool from rendering, media, and form-management siblings by focusing on geographic boundary retrieval.

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

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

The description provides clear context for when to use the tool: when a GeoJSON boundary is needed for a Map composition. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that no other sibling tool competes for this function. This is clear context without explicit when-not 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 mutating/non-destructive/non-idempotent. The description adds real context beyond that: batching cap of 10, parallel execution, per-item return of audio_url and caption_ref, and where results land. It stops short of noting that repeat calls produce duplicate assets (idempotency consequence), which would matter for a generation tool.

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

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

Purpose is front-loaded and paragraphs are organized by concern (usage, voice, tone, batching). It is longer than strictly needed, repeating voice descriptions that already appear verbatim in the schema enum, but no sentence is wasted.

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

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

An output schema exists, yet the description still tells the agent what comes back (audio_url, caption_ref) and how to consume it downstream, plus the voice/tone selection policy. Complete for an agent to call this correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds strategy beyond the schema: pick one voice for the whole form and reuse it, always set a tone matching the mood, and pass one or many items. That is guidance the schema text alone only partially conveys.

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

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

Opens with a specific verb+resource+output: 'Generate narration audio from text with word-level captions.' It is unambiguous against siblings (no other tool does TTS) and the scope of use is stated immediately.

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

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

Explicit when-to-use cases (quiz narration, survey intros, form instructions), proactive-suggestion guidance, and named downstream alternatives (clipform_render_composition / clipform_render_video_template / clipform_upload_media_asset) for attaching captions. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds some value by naming the returned fields (title, settings, node options/config/media status/next node) and attributing the routing to clipform_set_logic, but it discloses no auth, rate-limit, or failure behavior beyond what annotations and the output schema provide.

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

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

Two tight sentences, front-loaded with the primary purpose and then the return contents. Every clause carries information and nothing is padded.

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 rich annotations and a dedicated output schema, the definition only needs to orient the agent, which it does. The return-value description is somewhat redundant against the output schema, but the purpose and scope are complete enough to call the tool correctly.

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

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

Schema description coverage is 100%, so both form_id and context are already documented (including the useful note that form_id is not the short share_id). The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Retrieve) and resource (a form's details), and scopes the content precisely: all nodes in sequential order plus their routing. It is clearly a single-form read tool, distinguishable from clipform_list_forms and clipform_get_workflow, though it never names those siblings explicitly.

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?

There is no guidance on when to call this versus alternatives such as clipform_get_workflow or clipform_list_forms, nor any stated prerequisites. The usage context is only weakly implied by the content it returns.

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 false, so the safety profile is covered. The description adds valuable behavioral context by specifying the return format as markdown, detailing the information payload, and clarifying the exclusion of workflow content. This goes beyond what annotations alone provide.

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

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

The opening sentences are front-loaded with the core purpose and the crucial differentiation from clipform_get_workflow. The alias list is long but justified because alias resolution is essential for correct invocation. Slight redundancy exists in listing types twice, but overall the content is dense and purposeful.

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

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

For a read-only, idempotent knowledge-retrieval tool with no output schema, the description is complete: it explains what the result contains, its format, the accepted inputs, aliases, variants, and the key sibling exclusion. An agent has everything needed to select and correctly call this tool.

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

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

Schema coverage is 100%, but the description significantly enriches parameter understanding: it expands the 'type' parameter with the full list of supported types, an extensive alias map, and further clarifies the optional 'variant' parameter with its valid values and purpose. This is far more informative than the schema alone.

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

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

States a precise verb and resource: 'Retrieve craft knowledge for building a specific form type' and enumerates the concrete knowledge categories returned. Explicitly distinguishes itself from clipform_get_workflow, so an agent can differentiate it from the most closely related sibling without 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?

Directly states what the tool does not do and names the correct alternative: 'Does NOT return a step-by-step build workflow - use clipform_get_workflow for that.' It also provides the complete set of accepted types, aliases, and optional variant guidance, making the selection criteria explicit and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the response includes processing status, a genuine behavioral detail, but says nothing about what statuses exist or how pending vs. failed media appear.

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 sentences, purpose front-loaded, zero filler. Everything stated 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?

A read-only, output-schema-backed tool with fully documented parameters needs little more; the description supplies purpose and one use case. It could be slightly more complete by naming whether media can be multiple items or the status vocabulary.

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 parameter descriptions are rich (e.g., form_id warns to use the UUID rather than the share_id). The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (media attached to a node) plus the scope (processing status), which an agent can distinguish from clipform_search_media or clipform_attach_node_media. It never explicitly names a sibling, so differentiation is inferred from the node-scoped wording rather than stated.

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?

Offers one concrete scenario (checking whether a video upload finished processing), which is implied usage guidance. There is no when-not-to-use guidance and no routing to clipform_check_render or clipform_search_media for related checks.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial context beyond that: which answer types are redacted to placeholders (booking, contact, file upload, drawing, camera, recordings), that payment data is limited to a non-PII amount/status summary, that auth requires a signed-in account, and that the underlying responses URL comes from clipform_get_form.

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

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

Purpose and sibling differentiation are front-loaded, and the parenthetical redaction inventory is information-dense rather than filler. The single long run-on sentence is slightly heavy but nearly every clause 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?

With an output schema, full annotations, and 100% param coverage, the only remaining burden is behavioral nuance — redaction/PII limits, auth requirement, sort order, and where form_id comes from — all of which the description supplies.

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 every parameter including since/until ISO 8601 format and enum defaults is already documented. The description only restates the sort default and adds vague 'time filtering' language, which is baseline-level value on top of a self-documenting schema.

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

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

States a specific verb and resource ('List a Clipform form's individual responses (submissions)') with scope modifiers (time filtering), and explicitly contrasts it with clipform_get_results, which aggregates. An agent can distinguish the two without opening either schema.

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

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

Names the alternative (clipform_get_results for aggregates) and gives concrete example questions ('what came in during the last 24 hours', 'what's the longest answer') that map to this tool's use. No explicit 'do not use when' clause, so it stops just short of a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds genuinely new behavioral context: an authenticated Clipform account is required and anonymous sessions will be prompted to sign in. It also discloses a real data limitation (booking, contact, file upload, drawing, camera, payment nodes return counts only), which prevents the agent from promising per-response detail.

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 carrying a distinct payload: what you get, what you don't get, and what access is needed. Front-loaded with the returned content. Slightly dense but 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?

With an output schema present, the description doesn't need to explain return shapes, and it correctly focuses on the auth requirement and the node-type data limitations. The one missing piece for a tool in a 29-sibling server is routing guidance versus clipform_get_responses.

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 both parameters (form_id, context) are documented there, including the warning that form_id is the UUID not the share_id. The description adds nothing about parameters beyond what the schema already says, so the baseline 3 applies.

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

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

States a specific verb and resource ('View response counts, choice/action answer breakdowns, and recent open-text answers for a form'), so an agent knows exactly what data comes back. It fails to distinguish itself from the sibling clipform_get_responses, which by name alone looks like it does the same thing.

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 does name one alternative ('use the dashboard for per-response detail'), which is useful routing for detailed exports. But the sibling clipform_get_responses is never mentioned, so the agent has no guidance on when to pick one over the other.

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 a safe, read-only, idempotent, closed-world retrieval, so the safety profile is covered. The description adds useful substance beyond that by spelling out what the recipe contains (tool sequence, settings, scoring, end screen), which matters since there is no output schema. It stops short of noting anything about response size or downstream application of the recipe.

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

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

Front-loaded with purpose and the guide exclusion before the long tail of type/alias detail, so the critical routing information comes first. The exhaustive alias list is bulky but each mapping prevents a failed call, so it earns most of its space; the structure could still be tightened.

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

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

For an 18-parameter, no-output-schema tool this is complete: the agent knows the valid types, variants, per-type optional args and defaults, and what the response will contain. The required 'context' parameter is documented in the schema, and nothing needed to invoke correctly is missing from the description.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it maps which optional args apply to which type, states the question_count default of 8, and gives the full alias table (trivia→quiz, nps→survey, etc.) that the schema only gestures at. The tiering of args by type is information the flat schema cannot convey.

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

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

States a specific verb+resource ('Retrieve a step-by-step build workflow for creating a specific form type') and enumerates the returned artifacts (tool sequence, settings, node config, scoring, end screen). It explicitly differentiates itself from clipform_get_guide, so an agent can route without opening either schema.

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

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

Gives an explicit exclusion: 'Does NOT return craft knowledge… use clipform_get_guide for that,' naming the alternative and the condition selecting it. It also enumerates the valid type values and variant options, preempting the main failure mode of calling with an unknown type.

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 flag the call as non-read-only, non-destructive, open-world and non-idempotent; the description adds what actually happens: source form and responses stay untouched, private forms cannot be read, output is an unpublished draft, and unmappable question types are skipped rather than guessed with a per-item import/skip report. That is substantive behavioral context beyond structured fields.

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

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

Action is front-loaded in sentence one, then preconditions, then the required next step, then edge-case behavior. Every sentence carries either a constraint or a workflow instruction; nothing is redundant with the title.

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 mutating, open-world import tool with an output schema, the description covers sourcing, visibility requirements, draft state, follow-up publishing, and partial-import semantics. An agent has everything needed to call it correctly and to know what to do with the result.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value on the url parameter by enumerating accepted hosts and the sharing requirement (docs.google.com/forms.gle 'Anyone with the link', form.typeform.com/to/..., public tally.so). It says nothing extra about workspace_id or the context parameter, which the schema already documents.

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

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

The first sentence gives a specific verb+resource (copies questions) plus an exact source set (Google Form, Typeform, Tally) and destination (new Clipform draft). This clearly separates it from clipform_create_form (build from scratch) and clipform_get_form (read an existing 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?

States the key precondition (source must be publicly accessible) and the post-call workflow: the result is a DRAFT, review it, then republish via clipform_update_form with is_live: true — explicitly naming the sibling to chain to. It doesn't explicitly contrast with clipform_create_form for the from-scratch case, so not a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the asset category taxonomy, which is mild useful context, but says nothing about result volume, pagination, or whether the list is scoped to the user's workspace.

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 front-loaded sentence with no filler; verb and resource come first. It is appropriately sized, though the brevity is partly what leaves the usage and scoping questions unanswered.

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?

An output schema exists, so return values need not be described, and the annotations cover the safety profile. What remains missing is routing context against the many sibling list/search tools and any hint about result scope — enough to call it adequate but not complete.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents both the type enum and the context field. The description's enumeration of asset types loosely parallels the enum values but adds no filtering semantics or format detail beyond it — baseline 3 is appropriate.

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

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

States a specific verb (List) plus resource (creative assets) and enumerates the categories it covers (sound effects, animations, fonts), which maps directly to the enum. It does not, however, distinguish itself from nearby siblings such as clipform_search_music, clipform_search_media, or clipform_list_video_templates, leaving the agent to infer the boundary.

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

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

There is no when-to-use guidance and no mention of alternatives. With four list_* siblings and three search_* siblings in the toolset, the agent gets no signal about when listing assets is preferable to searching music or media, or how this relates to adding assets to a 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the fact that results include props schemas, but that is largely duplicative of the output schema, and it says nothing about result volume, pagination, or freshness of the catalog. Adequate but thin 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?

Three short sentences, front-loaded with the purpose, then the workflow ordering, then the exclusion. Every sentence earns its place with zero filler.

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

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

With an output schema present, the description need not explain return values, and it correctly covers purpose, ordering, and the sibling alternative. The only minor gap is the absence of any hint about catalog size or how to interpret the props schemas, but an agent has enough to call it correctly.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents 'context' including the instruction not to name the tool being called. The description adds no additional meaning for that parameter, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Browse available video compositions') plus the payload returned (expected props schemas), and explicitly distinguishes itself from the sibling clipform_list_video_templates. An agent can tell this apart from the template-listing tool without opening either schema.

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

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

Explicit ordering guidance ('Call this before using clipform_render_composition') and an explicit when-not with a named alternative route (video templates for image/photo montages, naming both list_video_templates and render_video_template). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds genuinely new behavior: cursor-based pagination, next_cursor presence, and an authentication prerequisite. It does not cover rate limits or result size, but the added context is substantive.

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?

Four tight sentences with the core action front-loaded, followed by pagination and the search shortcut. Slight overlap between the pagination sentence and the schema's cursor description, but no real 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 an output schema present, the description needn't explain return fields, and it sensibly limits itself to pagination mechanics and auth requirements. Coverage is adequate for a filtered-list tool with 9 documented parameters.

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 rich per-parameter descriptions (tags AND logic, defaults, cursor source, search semantics), so the schema carries the parameter burden. The description echoes the search/cursor behavior rather than adding syntax or constraints beyond it.

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

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

States a specific verb and resource ('List forms in your workspace') plus scope ('optional filtering'), which is clearly distinct from the sibling clipform_get_form. It does not, however, explicitly name that sibling or otherwise route the agent between list and single-retrieve.

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

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

Gives real usage direction: use search with part of a title instead of paging, and notes the signed-in-account requirement (anonymous sessions are asked to sign in). It stops short of stating when to prefer clipform_get_form over this list tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: what a template conceptually is, that it renders from a small controls object, and how it relates to the render tools. It does not discuss return shape, but an output schema exists so that burden is not on the description.

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

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

Three tight sentences: the first defines the resource, the second gives the workflow ordering, the third names the alternative. No filler, and the routing information is front-loaded enough to be actionable.

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

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

For a read-only list tool with full annotation coverage, a complete output schema, and a fully described single parameter, the description supplies everything else an agent needs: what the tool returns conceptually, when to call it, and which sibling to use instead. Nothing material is missing.

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

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

Schema description coverage is 100% and there is a single 'context' parameter whose description is already self-explanatory. The tool description adds no additional meaning about that parameter, so the baseline 3 applies.

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

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

States a specific verb and resource (browse/list video templates) and elaborates what a template actually is: a curated Scene arrangement of bed + overlay with sane defaults rendered through the Scene composition. This lets an agent distinguish it from clipform_render_video_template and clipform_render_composition without opening a schema.

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

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

Gives an explicit call ordering ('Call this before clipform_render_video_template') and names the alternative path for a different need ('for a fully custom layer stack, assemble Scene layers directly via clipform_render_composition instead'). Both the when and the when-not are spelled out with 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?

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so safety profile is covered. The description adds genuinely useful behavioral context beyond that: the tool is an internal audit step, not a user-facing action, and it must be the terminal step of the workflow. It does not discuss what happens on repeated calls despite idempotentHint=false, which keeps it from a 5.

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

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

Two sentences with the purpose front-loaded and the usage constraint immediately following. No filler, no restating of the title.

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 non-read-only audit logger with full schema coverage, clear annotations, and no output schema, the description supplies everything an agent needs: what it records, why it exists, and the precise workflow position it must occupy.

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%, including nested images/sources objects, so the schema does the heavy lifting and the baseline is 3. The description names the kind of content captured (sources, image attributions), which lightly maps to the 'details' parameter but adds no syntax or format guidance beyond the schema.

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

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

The description gives a specific verb+resource: it records content provenance (sources, image attributions) for a form that was just generated. It also positions the tool within the workflow ('internal audit step run by a form-generation workflow'), which separates it from siblings like clipform_create_form 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?

Explicit when-to-use ('only call it as the final step of a generation workflow you are running') and explicit when-not ('never in response to a plain create or edit request'). This is exactly the routing an agent needs to avoid misfiring this tool on ordinary form operations.

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 destructive/openWorld/non-idempotent, and the description adds real behavioral context beyond them: returns a public URL, batch renders fire in parallel with one job ID each, wait:true blocks while wait:false returns a job ID, and strict inputProps validation fails loudly rather than silently defaulting. It does not explain why the operation is flagged destructive (e.g. overwriting existing node media), which is the one remaining gap.

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?

Four tight paragraphs, front-loaded with purpose then formats then batching then tool selection. Every sentence carries routing or behavioral information, though the mode-placement rules are restated across the description and the schema, adding mild redundancy.

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

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

For a 10-parameter tool with nested objects and a full output schema, the description covers the decision path (which render tool), the batching model, the attachment workflow, and the caption pipeline. An agent has everything needed to call it correctly without extra exploration.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the single-vs-batch mode split, the 10-item cap, the top-level vs per-item placement of node_id/captions/caption_ref, and the preference of caption_ref over captions. That goes beyond restating schema text.

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

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

States a specific verb+resource ('Render a specialised video composition to MP4 or PNG') and immediately scopes it against the sibling render path by naming what it is for: custom animated visuals a video template can't provide. An agent can distinguish it from clipform_render_video_template without opening either schema.

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

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

Explicitly routes the agent: reach for video templates for recognisable form/quiz beats, the slideshow template for montages, and this tool 'only when neither fits.' It also specifies when to use single vs batch mode, that a render must be attached to its node, and that polling/chaining is unnecessary.

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 cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds non-obvious behavior: renders run through the Scene composition, wait=true returns a URL while false returns a job ID, and attaching to a node republishes a live form. It doesn't explain why destructiveHint is set or what a render overwrites, leaving one behavioral gap.

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 a clearly labeled 'Choosing a render tool' section. Efficient overall, though the workflow guidance is long and the attach/poll warning is stated in a slightly repetitive way.

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 9 parameters, nested captions, and an output schema present, the description supplies exactly the missing context: template discovery, control surface, alternative routes, and the attachment/polling workflow. Nothing an agent needs to invoke it correctly appears absent.

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 carries the baseline. The description genuinely adds meaning beyond it: node_id auto-attaches and republishes, caption_ref is preferred over captions and defaults to controls.audio_url for slideshow narration, and context should describe the user's goal rather than the tool call.

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

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

States a specific verb and resource ('Render a curated video template ... to MP4 or PNG') and immediately scopes it against hand-assembling Scene layers. It names the sibling tool it is not (clipform_render_composition) and the one to call first (clipform_list_video_templates), so the agent can discriminate without opening a schema.

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

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

Explicit routing rules: 'reach for a video template first' for form/quiz beats, slideshow template for montage, clipform_render_composition only when neither fits. It also states the prerequisite (call list_video_templates first) and the postcondition (attaching via node_id instead of polling or chaining upload+attach).

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/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds licensing context ('all results are pre-cleared for commercial use') and the presence of alt-text descriptions for picking visually distinct images, which annotations cannot convey.

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

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

Front-loads the core action, then the batching rule, then downstream routing, then licensing. Mostly tight, though the trailing example partially duplicates schema information and lengthens the definition without adding much new meaning.

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?

An output schema exists, so return-value explanation isn't required, yet the description still notes the alt-text field usefully. Combined with annotations and full schema coverage, an agent has enough to call this correctly; the only minor gap is no explicit pagination/limit guidance beyond per-query count.

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 query, kind, count, and orientation are all documented in the schema. The description adds an example showing the multi-query shape and a non-default count, but no semantics beyond what the schema already states. Baseline 3 applies.

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

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

States a specific verb (Search) and resource (images or stock video clips), immediately distinguishing it from sibling search tools like clipform_search_music and clipform_search_news. The scope and output type are 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?

Explicitly routes the agent downstream: results feed clipform_render_video_template for slideshows, or go through clipform_upload_media_asset then clipform_attach_node_media for stills. It also states the batching rule (up to 10 queries in one call instead of separate calls), which is a genuine when-to-use instruction.

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, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: results are royalty-free and include license info, and the returned URL is meant to be fed into clipform_render_video_template. It doesn't cover rate limits or result ordering, but the added licensing/workflow context is meaningful.

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?

Four sentences, purpose front-loaded, and the workflow instruction is placed before the return-value note. The 'keeps energy up between questions' clause is mildly chatty but does reinforce the usage guidance rather than being pure filler.

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

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

Purpose, usage context, and the downstream render_video_template integration are all covered, and annotations carry the safety profile. The only redundancy is restating return fields (download URLs, duration, artist, license) that the output schema already provides; otherwise an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including tag ANDing, count default, duration bounds, and instrumentalOnly default. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Search for royalty-free music tracks and ambient sounds.' That resource is specific enough to separate it from siblings like clipform_search_news and clipform_search_media on the surface, but the description never explicitly names an alternative, so the differentiation is left implicit.

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

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

Gives concrete when-to-use context ('Quiz forms especially benefit...', 'Also consider it for multi-step surveys and longer forms') and a downstream workflow hook (pass the URL to clipform_render_video_template). There is no explicit when-not-to-use or named alternative, which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds behavior that annotations do not: which providers are queried, the temporal coverage window (post-May-2025), and the per-result field list. Return format is partly redundant with the output schema, but the sourcing and coverage-window facts are genuine additions.

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

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

Three short, labeled blocks that are front-loaded with purpose, then coverage, then returns. Every sentence carries information; nothing is padding.

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 an output schema covering return values and annotations covering the safety/idempotency profile, the description only needs to cover sourcing and scope limits — and it does exactly that. There is no meaningful gap for an agent deciding whether and how to call 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 already documents all three parameters including the example queries and the unusual 'context' semantics. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Search recent news articles') and names the two upstream providers (NewsAPI, The Guardian), which immediately distinguishes it from clipform_search_media and clipform_search_music. The scope note ('recent events... post-May-2025') further pins down what the tool returns.

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

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

Gives an explicit negative boundary: 'Does NOT cover timeless topics (history, geography, science).' That is real when-not guidance an agent can act on. It stops short of naming an alternative tool for those cases, so it is clear context without a routed fallback.

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 and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful beyond-schema context: 'A call replaces that node's routing entirely - it does not merge with any prior target,' which concretely explains the destructive, non-merging replacement semantics.

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

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

Front-loaded with the core action in the first sentence, followed by batching rationale, exclusion, and an example. Well structured, though it runs a bit long; every element still carries 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 an output schema present, return values need no explanation, and the description fully covers the routing semantics, the replacement behavior, the batching capability, and the branching limitation. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema documents node_id, target_node_id, rules, and form_id. The description earns extra credit by supplying a concrete two-node JSON example that clarifies the nested nodes/rules structure and the one-rule constraint (maxItems 1) in practice.

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

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

States a specific verb and resource ('Set the next node for one or more nodes, wiring a linear route'), and explicitly distinguishes itself from branching logic, which it says is configured elsewhere. An agent can tell this apart from node-creation or update siblings without opening schemas.

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

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

Gives positive guidance (batch multiple nodes into one call rather than separate tool calls) and a clear exclusion with a redirect (branching by respondent choice is not configured here; it lives in the form's Build tab). Both when-to-use and when-not are explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description's job is narrower; it adds two genuinely new behavioral facts: this is a partial update where omitted fields are unchanged, and several parameters are AI-PROTECTED with constraints living in their parameter descriptions. It stops short of explaining what destruction is possible (e.g. taking a form offline by is_live:false), which remains only in the schema.

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

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

Three short sentences, front-loaded with the verb+resource and the partial-update contract immediately after. Little waste, though the AI-PROTECTED sentence is a pointer rather than content and could have been folded into the update rule.

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 17 parameters but 100% schema coverage, an output schema, and full annotations, the description carries a light burden and mostly meets it. It is thin on one thing an agent must decide unaided: when to use this versus clipform_update_node or clipform_create_form.

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 parameter docs are unusually rich (is_live publish semantics, tags replacement, AI-PROTECTED flags), so baseline 3 applies. The description only lists a subset of the 16 optional fields (title, publish status, settings, tags) and adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource plus the surface being edited ("title, publish status, settings, or tags"), which is clearly distinct from clipform_update_node's node-level edits. It does not explicitly name a sibling or scope boundary, so an agent still has to infer that this touches form-level metadata only.

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 second sentence implies usage (partial/patch updates are safe because omitted fields are untouched), but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as clipform_update_node or clipform_create_form. Guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the mutation risk is known. The description adds genuinely useful context — the position-change exclusion and the derivation of type/config schemas from @vid-master/config — but says nothing about the destructive consequences (e.g. that removing an option also removes its routes) or merge-versus-replace behavior, which live only in the schema.

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

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

Four sentences, front-loaded with the action, then batching, then prerequisites, then scope exclusion — a sensible ordering with no filler. The trailing sentence about @vid-master/config is an implementation detail of marginal value to an agent, but it is only one clause.

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 an output schema present the description needn't explain return values, and annotations plus a fully-described schema cover safety and parameter shape. What remains is covered — batching limits, ID sourcing, and position invariance — leaving only unaddressed failure modes such as what happens with a stale or unknown node_id.

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 form_id, updates, context and every nested field are already documented in the schema, setting the baseline at 3. The description only adds the provenance of node IDs and a pointer to clipform_get_guide, both of which the schema's own config description already mentions, so it adds little semantic value beyond structured fields.

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

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

Opens with a specific verb and resource ('Update one or more existing nodes') and enumerates the mutable facets: text, type, config, options. The clause 'Does not change node positions in the flow' draws a boundary that separates it from layout-oriented siblings, so an agent can identify the tool without opening the schema.

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

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

'Pass multiple updates in one call instead of separate tool calls' gives a clear trigger for using this tool over repeated single calls, and it states the prerequisite that node IDs must come from clipform_create_form, clipform_add_node, or clipform_get_form. It stops short of naming a specific alternative (e.g. add_node for new nodes or update_form for form-level edits), so the exclusion side is only partial.

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

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

Beyond the annotations, it discloses sequencing (sequential uploads), automatic storage-location selection by size/type, URL auto-fetch behavior, and a notable return-shape exception (PDFs return a document descriptor instead of a media_asset_id). This is substantial operational context the structured fields do not carry.

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

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

Front-loads the core action and is organized into short, scannable paragraphs, each carrying distinct information. It runs somewhat long and re-states the caption guidance in both the body and schema, but there is little pure filler.

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

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

For a 5-parameter, non-idempotent upload tool with an output schema present, the description covers everything an agent needs: entry point in the chain, the follow-up tool, input-source options, and the exception return path. Return-value details are appropriately delegated to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter guidance: media may come from items, files, or both (at least one required is not obvious since both are optional in the schema), and caption_ref should be preferred over manually copying the captions array.

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

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

States a specific verb and resource ('Put one or more media files into your workspace media library') with scope limits (max 10, uploaded sequentially). It explicitly distinguishes itself from the sibling clipform_attach_node_media by naming it as the required follow-up step.

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

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

Gives explicit workflow placement ('step one of attaching media to a node'), names the alternative follow-up tool, explains the mutually-alternative input paths (items vs files vs both), and spells out the PDF/consent-agreement case and the caption_ref-vs-captions preference.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: the call fails/clarifies for anonymous sessions by asking them to sign in, which is real auth-flow context an agent needs.

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

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

Two sentences, zero waste: the first front-loads what is returned, the second states the auth prerequisite. Nothing needs to be re-read or inferred.

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

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

For a read-only identity tool with an output schema present, return-value documentation is unnecessary, and the description still goes further by naming the returned fields. The auth prerequisite closes the only remaining gap.

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

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

There is a single 'context' parameter with 100% schema description coverage, so the schema already explains its meaning. The description adds nothing about how to phrase the context string, which is the correct baseline 3 when the schema does the work.

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

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

States a specific verb ('show') and resource ('current identity'), then enumerates the exact payload: auth mode (with its four possible values), active workspace, and plan limits. No sibling tool in the list overlaps with an identity/whoami query, so the agent can route to it unambiguously.

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 conveys the use context (checking auth mode, workspace, and plan limits) and states the prerequisite that a signed-in account is required, with anonymous sessions being redirected to sign in. It stops short of explicit when-to-use/when-not phrasing or naming alternatives, but there is no competing sibling to disambiguate against.

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 safety profile is covered. The description adds no additional behavioral context such as what 'check' entails, whether it makes a network call, or what side effects (if any) occur 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 a single, front-loaded sentence with no wasted words. It quickly communicates the action and the conditions for use, making it efficient and easy to parse, though it could be slightly more structured with a separate usage note.

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 gives clear usage guidance but does not explain what the tool returns or what happens after 'checking' for tools. With no output schema present, the description carries the burden of explaining the result, which it fails to do. For a simple one-parameter tool, this is a notable gap, though not severe.

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 single parameter 'context' is already documented with a clear description in the schema. The tool description adds no additional semantic meaning beyond what the schema provides, which aligns with the baseline of 3.

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

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

The description clearly states the tool's function: checking for additional tools when a task could benefit from specialized capabilities. It distinguishes itself from the sibling clipform_* tools by being a meta-tool for tool discovery rather than a domain-specific operation, though it does not explicitly name this distinction.

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

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

The description provides explicit usage guidance: use this tool whenever specialized capabilities might help, even if existing tools could work as a fallback. This gives the agent a clear decision rule, though it does not mention when not to use it or list alternative tools.

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