Clipform

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real behavioral context beyond them: default append-before-end-screen placement and automatic chain re-linking on linear insert. It does not spell out that repeated calls create duplicate nodes or note any permission requirements, so it is strong but not exhaustive.

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

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

Three sentences, all front-loaded and purposeful: purpose, insertion mechanics, then the logic-relinking implication. No filler or restatement 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 mutation tool with a nested node object, an output schema, and full annotation coverage, the description supplies the key operational facts (positioning, relinking, where to find config schemas). It leaves minor gaps around duplicate-insert semantics and permissions, but nothing that would cause a misinvocation.

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 more by clarifying default insertion ('Inserted before the end screen by default; after_node_id controls insertion position') and by cross-referencing clipform_create_form and clipform_get_guide for config shapes rather than duplicating them.

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 ('Add a new node to an existing form') and immediately scopes it with default insertion position, cleanly separating it from siblings like clipform_update_node and clipform_delete_node. It also anchors node typing to clipform_create_form, so an agent knows the shapes before 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 explicit when/when-not guidance: use this for a simple insert because linear re-linking is automatic and 'you do not need clipform_set_logic', while branching 'still needs an explicit logic write'. It names the alternative tool and the condition that selects it.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), but the description adds substantial behavior they cannot: authenticated sessions land the form in the user's workspace, anonymous sessions produce drafts with a private preview link where answers are not saved, and some results carry a one-time claim URL that must be relayed. That is exactly the kind of side-effect and auth context an agent needs before writing.

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 correctly: purpose, then return/claim behavior, then creation guidance, then the node reference, then a worked example. The node-type catalog is long but mostly load-bearing given the opaque config schema; it is organized as scannable bullets rather than prose. Slightly oversized, since it both defers craft guidance to clipform_get_guide and inlines a full config reference.

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, 8-node-type creation tool with an opaque config schema, the description supplies the node shapes, defaults, and an end-to-end example. An output schema exists, so return values need not be explained, yet the viewer URL / form ID / claim URL details are still disclosed. Nothing an agent needs to construct a valid call 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 coverage is 100%, so the baseline would be 3, but the `config` property is an opaque object (additionalProperties: {}), meaning the description carries the entire burden for config semantics. It enumerates every node type with its config keys, allowed values, and defaults, which the schema does not provide at all.

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 opening sentence states a specific verb and resource — 'Create a new Clipform (interactive video-style form)' — and the parenthetical disambiguates it from generic form tools. An agent can separate this from siblings like clipform_update_form, clipform_import_form, and clipform_add_node purely from the verb and the node-catalog framing.

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

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

It gives a conditional branch for the empty-prompt case ('If the user hasn't said what to build yet, offer to build their first form') and points to clipform_get_guide for craft guidance and clipform_whoami for workspace IDs. However, it never explicitly says when to prefer this over clipform_import_form or when to fall back to clipform_add_node on an existing form, so the routing 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 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?

Goes well beyond the annotations: explains the automatic re-linking side effect (previous node points to the next), states which nodes are ineligible, and flags the user-confirmation requirement. Annotations already say destructive/idempotent, but the description adds the specific mutation semantics that matter for a delete.

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 load-bearing and front-loaded: action first, then consequence, then constraints and prerequisite. 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 single-resource tool with no output schema, the description covers the mutation effect, the guardrails, and the confirmation flow — everything an agent needs to decide and call 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% and each parameter (confirm, context, form_id, node_id) is documented in the schema itself. The description's 'Requires user confirmation' sentence lightly reinforces the confirm parameter but adds no syntax or format 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?

States a specific verb+resource ('Delete a node from a form') and immediately adds the behavioral consequence (re-linking), which distinguishes it from clipform_delete_node_media and clipform_delete_form 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?

Gives explicit when-not conditions ('Cannot delete the start node or the last end screen') and a confirmation prerequisite, which is strong context. It stops short of naming an alternative sibling or the workflow for restructuring before deletion, so it is 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by specifying what is destroyed (media record, stored asset, and third-party provider copies) and by stating the confirmation requirement. It stops short of describing irreversibility, failure modes, or downstream effects on the node.

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 action and its destructive scope, followed by the confirmation prerequisite. No filler or redundancy.

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

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

For a destructive tool with rich annotations and a fully documented schema but no output schema, the description covers what is deleted and the confirmation gate. It omits what the caller should expect afterward (return value, node state) and whether the deletion can be undone, which would be the final useful additions.

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 the confirm flag and form_id (UUID vs share_id), so the schema carries the parameter burden. The description adds no parameter-level detail beyond what the schema already provides, 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 ('Remove/Deletes') and resource ('media from a node') and clarifies the exact scope of deletion — the media record plus the stored asset. An agent can distinguish this from clipform_get_node_media, clipform_attach_node_media, and clipform_delete_node 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 description gives one prerequisite ('Requires user confirmation before it runs'), which is genuinely useful context. However, it names no alternatives or when-not-to-use conditions, and never distinguishes itself from sibling media tools like attach_node_media or delete_node explicitly.

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, non-destructive), yet the description adds substantial undisclosed behavior: contact details, file uploads and audio/video answers are redacted to placeholders, a non-PII payment summary is returned, full payment details remain in the dashboard via the URL from clipform_get_form, and a signed-in Clipform account is required. That is exactly the kind of auth, privacy and result-shaping context annotations cannot express.

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 scoping distinction from clipform_get_results is front-loaded and each sentence carries information (redaction, auth, ordering). It is a dense single paragraph with mild redundancy in the illustrative questions ('what's the longest answer', 'what did people say'), but nothing is wasted enough to warrant cutting.

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 7-parameter, read-only list tool with an output schema, the description covers everything the agent still needs: what is filtered, what is redacted, what the ordering default is, and the authentication prerequisite. Return-value shape is correctly left 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 description coverage is 100%, so every parameter (sort, limit, query, since, until, form_id, context) is already documented in the schema. The description restates the sort default ('newest first unless sort: oldest') but adds no syntax, format or constraint 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 and resource ('List a Clipform form's individual responses (submissions)') and immediately distinguishes itself from the closest sibling by noting it 'complements clipform_get_results (aggregates)'. An agent can tell which of the two listing tools to pick 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 contrasts this tool with clipform_get_results (aggregates), so the alternative is named and the split is implied, and it supplies concrete scenario questions ('what came in during the last 24 hours', 'what's the longest answer'). It stops short of an explicit when-not rule (e.g. 'do not use this for totals or charts'), so it is clear context rather than a full routing decision.

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 establish readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the bar is lowered. The description still adds real value beyond those: it discloses the answer-type aggregation constraint and the authentication requirement (anonymous sessions are told to sign in), which the annotations do not 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?

Three sentences, front-loaded with what the tool returns, then the aggregation caveat, then the auth prerequisite. No filler, though the sentence order slightly buries the auth requirement at the end.

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

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

With an output schema present, return format need not be described, and annotations cover the safety profile. The description covers scope, limitations, and auth, leaving only the sibling differentiation from clipform_get_responses unaddressed.

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 are documented in-schema (form_id as UUID vs. share_id, context as goal statement). The description adds no parameter guidance, so the baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('View response counts, choice/action answer breakdowns, and recent open-text answers for a form'), naming the exact data returned. However, it does not distinguish itself from the sibling clipform_get_responses, which appears closely related, so an agent cannot tell the two apart from the description alone.

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 exclusions and context: answers of type contact/file/draw/camera/payment are counts only and per-response detail requires the dashboard, and a signed-in account is required. It stops short of routing the agent between this tool and the near-identical clipform_get_responses sibling.

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 declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely non-obvious behavior: the new form lands as a DRAFT, unmappable question types are skipped rather than guessed, and the result reports imported vs skipped with reasons. It does not address idempotency (annotation says non-idempotent) or auth/permission needs, so it is strong but not 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?

Front-loaded with the core conversion, then prerequisites, then the draft/republish workflow and skip-reporting behavior. Every sentence carries information, though it is on the longer side and could be trimmed slightly without loss.

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 annotations covering the mutation profile and an output schema existing, the description need only cover purpose, prerequisites, and the workflow step — all present, including the draft state and the skip-reporting contract. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description earns above that by enumerating accepted URL shapes (docs.google.com, forms.gle, form.typeform.com/to/..., tally.so) that the generic 'Public URL' schema text does not convey. The context and workspace_id parameters get no added meaning in the description.

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

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

The description opens with a specific verb+resource: converting a public Google Form, Typeform, or Tally form into a new Clipform. This clearly distinguishes it from siblings like clipform_create_form and clipform_update_form 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?

It states the precondition (source form must be public, with per-provider sharing requirements), and routes the agent explicitly: the result is a draft, and republishing happens via clipform_update_form (is_live: true). Both when-to-use and the follow-up step are spelled out.

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 safety profile is covered. The description adds genuine context beyond that: partial-update merge behavior and the existence of AI-PROTECTED parameters whose restrictions live in the schema. It does not warn about the tag-replacement overwrite, but the schema does.

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 compact sentences with zero filler; the patch-semantics rule is front-loaded immediately after the purpose statement, which is exactly what an agent needs before filling the 16-parameter schema.

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 16-parameter mutation with an output schema and fully documented parameters, the description covers the essential non-schema facts (partial update, protected fields). A note on how republishing interacts with prior edits would round it out, but the schema already carries that detail.

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 every parameter carries a detailed description (including AI-PROTECTED notes and publish semantics), so the baseline of 3 applies. The description adds only the high-level field categories, not syntax or meaning beyond the schema.

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

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

States a specific verb ('Update') plus resource ('a form') and enumerates the field families affected (title, publish status, settings, tags). An agent can separate it from clipform_create_form, clipform_delete_form, and clipform_update_node, though it does not name 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?

The patch semantics ('only sends fields that are provided - omitted fields remain unchanged') implies how to call it, but there is no explicit when-to-use guidance or comparison against alternatives such as clipform_update_node or clipform_set_logic. Usage must be inferred.

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 safety profile is covered. The description adds that node positions are untouched and where ID sources come from, but does not warn that passing 'options' replaces the entire set or that a type change discards the stored config, both of which are destruction-relevant.

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, front-loaded with the capability and batching rationale before the ID prerequisite and the positional exclusion. No filler, though the trailing config-source sentence is somewhat dense.

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 and annotations present, the description need not explain returns or safety. It covers batch semantics, ID provenance, and points to clipform_get_guide and @vid-master/config for per-type shapes, leaving little an agent needs but lacks.

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 form_id, updates, context and every nested field including merge semantics. The description's only added framing is that node IDs come from create/add/get calls, which is marginal 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 ('Update one or more existing nodes') and enumerates the mutable aspects (text, type, config, options). It does not explicitly differentiate itself from nearby siblings like clipform_update_form or clipform_set_logic, so it stops short of a 5.

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 batching guidance ('Pass multiple updates in one call instead of separate tool calls') and an exclusion ('Does not change node positions in the flow'). It omits when to prefer a sibling such as clipform_set_logic for logic changes, so no explicit alternative 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?

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.