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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, and destructive=false, so the mutation profile is covered. The description adds real behavioral context beyond that: Vimeo rejects two chapters sharing a second, which is an error condition an agent must avoid. It omits auth requirements, return shape, and per-video chapter limits.

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

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

Two sentences, zero filler, and the core action is front-loaded before the edge-case constraint. Every sentence carries information an agent needs.

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 three-parameter mutation tool with full schema coverage, no nested objects, and annotations covering the safety profile, the definition is nearly sufficient; the duplicate-second gotcha is the highest-value addition. It does not describe what is returned or confirm scope (single video), but no output schema exists to carry that.

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 all three parameters are already documented, setting a baseline of 3. The description adds meaning beyond the schema for timecode_seconds by explaining that timecodes must be distinct across a generated set, which is a constraint the schema does not express.

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

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

The description states a specific verb and resource ('Add a chapter marker') plus the anchoring parameter ('at a timecode'), which naturally separates it from the sibling list_chapters, update_chapter, and delete_chapter. It does not explicitly name those siblings, so it stops short of full differentiation.

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 supplies a usage scenario ('when generating a set from a transcript') and a constraint on that scenario, but never states when to prefer this over update_chapter or how it relates to the existing chapter list. Usage is implied rather than routing the agent between alternatives.

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

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

Beyond annotations, it discloses two meaningful traits: the comment is publicly visible to anyone who can see the video, and an auth scope (interact) is required along with a confirm flag. It stops short of covering rate limits or irreversibility, so not quite 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 short sentences with zero filler, and the core action plus its visibility warning are front-loaded. Every sentence carries information the agent needs.

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 3-parameter, no-output-schema tool with rich annotations and 100% schema coverage, the description covers the key gaps: public visibility, required scope, and the confirm gate. Nothing essential to correct invocation 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 already documents text, video_id, and confirm. The description restates the confirm: true requirement but adds no syntax, format, or constraint detail beyond what the schema provides; 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 ('Post a comment on a video') and clarifies the actor with 'as you'. An agent can distinguish it from sibling tools like edit_comment, delete_comment, and list_comments 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 supplies prerequisites ('Needs the interact scope', 'Requires confirm: true'), which is useful context, but gives no explicit when-to-use vs alternatives routing and no when-not guidance. Usage 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds a genuinely important behavioral fact not in the structured data: 'A video lives in one folder at a time, so this moves it rather than copying it.' It does not state what happens when the video is already in the destination folder or any permission requirements.

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, front-loaded with the core action, then the efficiency rationale, then the crucial move-vs-copy semantics. 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 two-parameter mutation with annotations covering safety and idempotency and no output schema, the description supplies the batch rationale and the move semantics an agent needs. It leaves edge-case behavior (already-in-folder, folder limits) unspecified, a minor gap.

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

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

Schema description coverage is 100%, so folder_id and video_ids (including the 100-item cap) are already documented in the schema. The description's 'pass the whole list' reinforces the array parameter but adds no new 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 (add), resource (videos), and target (folder), plus the batch scope 'one or many ... in a single call'. It is immediately distinguishable from the sibling remove_videos_from_folder and from per-item alternatives.

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

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

Explicitly tells the agent when to prefer this tool: 'the efficient way to file a back catalog: pass the whole list rather than calling once per video'. It does not name a when-not case or an alternative sibling tool, but the usage condition is clear.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world. The description adds genuine value beyond them by clarifying the side effect ('the video stays where it is in your library and is not moved') and the underlying API constraint. It stops short of stating auth/permission requirements or the response shape.

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, then the side-effect clarification, then the rationale for the one-at-a-time design. Every sentence earns its place with no repetition of the 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 two-parameter mutation with no output schema, the description covers what the tool does, its side effect, and its calling pattern. The only gap is the return value / error behavior, which is minor here.

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 parameters (showcase_id, video_id) are already documented in the schema. The description only reinforces cardinality (one video per call), which the schema cannot convey, but adds no format or ID-namespace detail. 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 ('Add one video to a showcase') and pins the cardinality ('one video', 'once per video'). It also implicitly distinguishes itself from any bulk variant by explaining that the bulk endpoint is deliberately not exposed, so an agent knows exactly what this tool does.

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 concrete usage rule ('Call this once per video') and explains why no bulk alternative exists, which preempts the agent hunting for one. It does not explicitly route to the sibling remove_video_from_showcase or state prerequisites, so it is strong but not fully explicit about alternatives.

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

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

Annotations already cover the safety/idempotency profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context: the operation is effectively a no-op unless embed privacy is whitelist. It does not describe auth requirements or the response, but the key precondition is disclosed.

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

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

Two tight sentences with the core action front-loaded and the precondition second. No filler text.

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

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

For a two-parameter mutation tool with full schema coverage and annotations, the description supplies the one critical thing the structured fields cannot: the whitelist precondition. Nothing an agent needs 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 already documents both video_id and domain. The description adds no syntax or format meaning beyond 'a specific domain', 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 (allow) and resource (a domain to embed a video), and the effect is unambiguous. It is clearly distinguishable from sibling tools like apply_embed_preset or list_embed_presets.

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 names the condition under which the call matters ('only takes effect when the video's embed privacy is set to whitelist') and routes the agent to the predecessor tool ('set that with update_video first'). This is exactly the when-to-use guidance an agent needs.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeatability profile is covered. The description adds the branding effect, which is useful context, but says nothing about permissions, whether an existing preset is replaced, or what failure looks like.

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 the action and the outcome; nothing is wasted or redundant.

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

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

For a simple two-parameter tool with full annotation coverage and no output schema, the description is nearly sufficient. Only minor gaps remain, such as what happens if a preset is already applied or whether the operation requires ownership rights.

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 both parameters are documented in the schema, so the baseline is 3. The description adds no additional meaning about video_id or preset_id beyond what the schema already states.

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 and resource ('Apply a saved embed preset to a video') and even states the effect ('player matches your branding'). It is clearly distinct from sibling list_embed_presets, though it never names that sibling directly.

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 explicit guidance on when to use this tool versus alternatives, nor any prerequisite statement. The link to list_embed_presets appears only in the schema parameter description, not in the tool description, so 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds the required 'create' scope, which is genuine context the annotations do not provide, but it says nothing about duplicate-name behavior or side effects of the non-idempotent create.

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 with the purpose front-loaded and no filler. The prerequisite sentence is slightly clipped but still earns its place by naming the scope requirement.

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 single-parameter create tool with annotations covering safety and no output schema, the description covers purpose and auth adequately. It omits what happens on duplicate names and what the call returns, which an agent calling a non-idempotent creator would benefit from knowing.

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% for the single 'name' parameter, so the schema already documents the input fully. The description adds no syntax, naming-rule, or format detail beyond it, making the baseline 3 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 and resource ('Create a folder'), which is unambiguous against siblings like create_showcase or upload_video. It does not, however, differentiate itself from related folder operations such as add_videos_to_folder or update_folder, 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?

There is no when-to-use guidance and no mention of alternatives or exclusions. The only extra sentence is a prerequisite ('Needs the create scope'), which is authorization information rather than usage context.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), lowering the bar. The description adds the required create scope, which is exactly the kind of auth context the rubric credits, but it says nothing else about behavior (e.g., whether the new showcase starts empty or what is returned).

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 with no wasted words and the purpose front-loaded before the prerequisite. It is efficient, though the brevity borders on under-specification rather than optimal conciseness.

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

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

For a 5-parameter creation tool with no output schema, the description covers only purpose and auth scope. It omits what the caller gets back (e.g., the new showcase identifier) and any note about the created resource's initial state, leaving the definition minimally adequate.

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

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

Schema description coverage is 80%, so the schema already documents name, sort, privacy, and password (including the conditional password requirement). The description adds no parameter meaning whatsoever, 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?

"Create a showcase" states a specific verb and resource, and the resource noun distinguishes it from siblings like create_folder and create_chapter. However, the sentence is a near-verbatim restatement of the tool title and adds no scoping detail beyond the name, so it does not reach the 5 tier.

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?

"Needs the create scope" gives an actionable prerequisite, which helps an agent confirm it can call the tool. There is no explicit when-to-use vs alternatives guidance (e.g., versus update_showcase), but the verb/resource pairing makes the intent inferable.

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=false. The description adds meaningful blast-radius context ('the video is untouched') so the agent knows only the marker is destroyed, plus the confirm requirement — useful disclosure beyond the structured fields.

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

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

Three short sentences, purpose front-loaded, zero filler. Each clause (scope, safety clarification, prerequisite) earns its place.

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

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

For a simple 3-parameter delete, annotations carry the safety profile and the schema carries the parameters; the description supplies the missing safety nuance. Little is missing, though still no note on failure modes or return value.

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 confirm, video_id and chapter_id are already documented. The description only echoes the confirm requirement and adds no syntax or format detail beyond the schema; 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 (delete) and resource (chapter marker), with explicit scope ('one'). The 'The video is untouched' clause immediately distinguishes it from delete_video and other deletion siblings, so an agent can place it without opening the schema.

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

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

The description conveys the confirm: true prerequisite, which is real usage guidance, but gives no explicit when-to-use vs alternatives such as update_chapter or delete_video. Usage 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=false, so the safety profile is largely covered. The description adds a specific behavioral requirement — that the confirm flag must be set to true — which is not present in the annotations and is important for correct invocation. However, it does not elaborate on permanence or permission needs, so it falls short of maximal transparency.

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

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

The description is two short sentences with zero wasted words, and the confirmation requirement is front-loaded alongside the core action. It is appropriately sized for a simple destructive operation.

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

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

Given the tool's simplicity, full schema coverage, and annotations that already flag destructiveness and non-idempotency, the description covers the essential action and the critical confirm requirement. The only meaningful gap is the lack of usage guidance relative to sibling comment tools, but the core invocation needs are met.

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 every parameter documented, so the schema already carries the full burden of parameter explanation. The description mentions only the confirm parameter and adds no syntax or format details beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific verb ('Delete') and resource ('comment from a video'), clearly distinguishing it from siblings like add_comment, edit_comment, and list_comments. An agent can immediately tell what the tool does without opening the schema.

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

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

The description offers no guidance on when to use this tool versus alternatives (e.g., edit_comment for modifications) and does not mention any prerequisites or exclusions. It only restates the action and a confirmation requirement, leaving usage context entirely implicit.

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 flag destructiveHint=true and idempotentHint=false, but the description adds non-obvious behavior: the default is non-destructive for contained videos (they return to the main library), the delete scope is required, and confirmation is mandatory. That materially improves an agent's ability to act safely. Minor gap: it doesn't describe what happens to empty folders or nested folders.

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, front-loaded sentences with essentially no filler; the destructive-default caveat comes early. The opening clause duplicates the title verbatim, which is a small 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 3-parameter mutation tool with no output schema, the definition covers scope, confirmation, and the key default behavior, which is enough to call it correctly. It omits edge cases such as nested folders or behavior when the folder is empty/already deleted.

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 meaning by explaining the default outcome of delete_videos_too (videos survive and return to the main library) and the hard requirement of confirm: true. These are outcome semantics beyond the schema's terse field 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 and resource ('Delete a folder') and immediately adds the consequential scope detail that contained videos survive by default, which is the key differentiator from delete_video. It does not explicitly name a sibling to contrast with, 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 prerequisites ('Needs the delete scope. Requires confirm: true.') which is real context, but says nothing about when to choose this over delete_video or remove_videos_from_folder, nor any when-not guidance. Usage is implied rather than framed.

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 flag destructiveHint=true and non-idempotency, but the description goes further by disclosing the blast radius (videos are preserved, curated order and branding are permanently lost) and the authorization requirement (delete scope). That is exactly the beyond-annotations context an agent needs before firing a destructive call.

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, then the consequence, then the prerequisites. Every sentence carries distinct information and none repeats the schema or title verbatim.

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 two-parameter destructive mutation with no output schema, the description covers what is destroyed, what is preserved, and the scope/confirm prerequisites. The only gap is that it never states outright whether the deletion is reversible or what error surfaces when confirm is omitted, though the annotations imply non-idempotency.

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 documents both showcase_id and confirm with its 'only when the user asked for exactly this action' wording. The description's 'Requires confirm: true' restates rather than extends that semantics, 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 showcase') and immediately disambiguates from the other delete_* siblings by naming the exact entity. It also scopes the operation by explaining that contained videos survive while the showcase's order and branding do not, so an agent knows precisely what is removed.

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 invocation preconditions ('Needs the delete scope', 'Requires confirm: true'), which is real usage guidance, but it never states when to prefer this over alternatives such as update_showcase or when deletion is inappropriate. Usage is implied rather than routed.

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=false and readOnlyHint=false, so the safety profile is covered. The description's only added behavior is the confirm requirement, which is essentially a restatement of the schema's confirm field and does not disclose irreversibility or what data is lost.

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, zero filler, and the confirm prerequisite is front-loaded where an agent will see it before constructing the call. Nothing could be removed without losing information.

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

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

For a destructive tool with full schema coverage and annotations carrying the safety profile, the description is nearly sufficient; it flags the required confirmation gate. It stops short of stating that the deletion is permanent and what happens to affected transcripts, which would be a useful omission to close.

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 video_id, track_id and confirm are already documented in the input schema. The description contributes no additional syntax, format, or meaning beyond what the schema 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 (Delete) plus a precise resource (caption track from a video), which cleanly separates it from siblings like delete_video, delete_chapter, delete_comment, and update_texttrack/upload_texttrack. An agent can select it 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 adds one concrete gating rule (requires confirm: true), which is real usage guidance, but it says nothing about when to prefer this over alternatives or when not to use it. Usage is largely implied by the tool name 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=false, but the description goes well beyond them: it discloses that the source file is removed, every embed breaks everywhere, Vimeo keeps no copy to restore from, and a specific scope is required. This is exactly the kind of irreversible-impact and auth context an agent needs before a destructive call.

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 and its consequences, then prerequisites. Every sentence carries distinct information with no 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?

For a two-parameter destructive tool with no output schema, the description covers impact, irreversibility, scope requirement, and the confirm gate. Nothing an agent needs in order to invoke it safely 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 baseline is 3, but the description adds real meaning by stating 'Requires confirm: true' even though the schema marks confirm as optional (only video_id is required). That corrects a potentially misleading schema signal.

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 (delete) and resource (video) with the key qualifier 'permanently'. It is unambiguous against siblings like delete_folder, delete_showcase, and delete_comment because the resource and effect are both named.

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 two concrete prerequisites: the delete scope (noting many tokens lack it) and confirm: true. There is no sibling that competes for this action, so a when-not-to-use clause is less critical, but the description doesn't explicitly frame when this should be preferred over update_video or similar.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), covering the safety semantics. The description adds the useful ownership restriction, but says nothing about what the edit overwrites, whether the original is recoverable, or auth requirements beyond ownership.

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, zero filler, with the core action front-loaded and the key constraint immediately after. Nothing can be cut without losing 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?

All three required params are documented and the safety profile is carried by annotations, so an agent can call it correctly. But the description is thin for a mutation tool: no note on response/return, no handling of invalid or non-owned comment ids, and no mention of the idempotent behavior already hinted by annotations.

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 three parameters (text, video_id, comment_id) are already documented in the schema, including the replacement semantics of text. The description adds no parameter-level detail, which is acceptable given the baseline.

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

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

States a specific verb+resource (edit a comment) and adds the ownership scope, which is genuinely differentiating. It doesn't name the sibling alternatives (add_comment, delete_comment, list_comments), so it lands just 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?

The ownership constraint implies when this applies (your own comments only) and when-not (someone else's). However, it never routes to a sibling tool or states prerequisites, so usage is only implied rather than 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 readOnly/idempotent/non-destructive, but the description adds genuine behavioral context not present in structured data: the required scope being off by default, and that links are signed and expire within hours. That expiry detail is exactly the kind of trait an agent must know to avoid handing out stale URLs.

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 with zero filler: purpose first, then the scope requirement, then the exclusivity claim. Every sentence carries distinct, decision-relevant information and nothing is repeated from the schema or annotations.

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, single-parameter tool with no output schema, the description covers purpose, auth prerequisite, result lifetime, and uniqueness. An agent has everything needed to decide to call it and to interpret its output safely.

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% for the single video_id parameter, so the schema already carries the parameter documentation. The description adds no format or syntax detail beyond referring to 'a video's source and rendered files', 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 ('Get direct download URLs for a video's source and rendered files') and clarifies the scope of what is returned. No sibling tool offers downloads, so differentiation is inherent and the description makes the unique purpose explicit.

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 prerequisite ('Needs the video_files scope, which is off by default on a new token') and a routing statement ('the only way to retrieve an original file through the API'). It does not name an alternative sibling to use for other retrieval needs, but the prerequisite context is unusually 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered without the description. The description adds nothing behavioral beyond that — it does not mention pagination behavior, that per_page caps at 100, or how video listing interacts with include_videos. With annotations carrying the safety burden, this is thin.

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, padding, or redundancy. It is efficient, though its brevity reflects under-specification rather than disciplined trimming. No structural or organizational problems.

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

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

For a tool with three parameters, one required, a default-true flag, and no output schema, the description should explain what the response contains and how paging applies. It says nothing about return shape, pagination limits, or empty-folder behavior. Annotations cover safety but the operational picture is incomplete.

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 67%: folder_id and include_videos are already documented in the schema, while per_page is undocumented in both places. The phrase 'the videos inside it' loosely maps to the include_videos flag, but the schema already explains that parameter, so the description adds no new semantic detail. Baseline 3 applies when the schema does most of 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?

The description states a verb ('get') and resource ('folder') plus the notable side effect of returning contained videos, so the operation is identifiable. However, it is a verbatim restatement of the title and does not distinguish this tool from close siblings like list_folders or get_video beyond the name itself. It lands at minimum-viable clarity rather than a distinguishing statement.

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 use this versus list_folders (many folders) or get_video (a single video), and no prerequisites or exclusions are given. The agent must infer routing purely from the tool name. No when/when-not/alternative information is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by naming what the call returns (plan, upload quota, token scopes), including quota and permission information that matters when deciding whether subsequent uploads will succeed.

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 that leads with the identity/scope of the call and appends the returned fields. No filler, no redundancy with the title.

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

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

There is no output schema, so the description carries the burden of describing the return, and it does so reasonably by naming the four main fields. It does not, however, describe the shape or nesting of the response (e.g. quota units, scope list format), leaving a small gap for a tool whose whole value is its payload.

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

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

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description's field list describes outputs, not inputs, and does not create confusion about arguments.

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 (the Vimeo account this server is connected to), and enumerates the returned fields: name, plan, upload quota, token scopes. No sibling tool returns account/identity data, so it is easily distinguished from the video-, folder-, and showcase-oriented siblings.

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

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

The description implies usage (verify which account and token capabilities are in play) but never states when to call this versus other tools, nor any prerequisite or exclusion. For a zero-parameter, side-effect-free tool this is acceptable but there is no explicit 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds one genuinely useful trait beyond the annotations: videos come back in their curated order, implying ordering is author-defined rather than by date. It says nothing about pagination even though per_page exists.

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 short sentence with the resource and the return scope front-loaded. No padding or redundant 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 read-only lookup with no output schema, the description usefully signals what comes back (the showcase plus its ordered videos). However, it omits pagination behavior for a tool that exposes per_page up to 100, leaving an agent unaware of result limits.

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 only 33%: showcase_id is documented in the schema, while per_page and include_videos are not described anywhere. The phrase 'and the videos in it' loosely hints at the include_videos toggle, but the pagination parameter is entirely unaddressed, so the description does not compensate for the coverage gap.

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 (get one showcase) and adds scope (also returns the videos, in curated order), which separates it from list_showcases and get_video. It does not name an alternative, but the singular 'one showcase' is 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?

Usage is only implied: fetch a single showcase by id. There is no statement of when to prefer this over list_showcases or get_video, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that: it picks the active track unless a language is named, and it strips cue numbers and timestamps by default. It does not mention failure modes for missing tracks, which keeps it out of 5 territory.

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 core purpose, followed by track selection, return shape, and the format escape hatch. Every sentence carries information an agent needs.

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

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

With no output schema, the description supplies the return shape itself ('the words only, with cue numbers and timestamps stripped') and covers both optional parameters. Nothing material for correct invocation 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% and the schema already documents format (text strips timings, vtt is raw WebVTT) and language (omit for active track). The description largely restates these, adding only the framing that vtt is for 'keeping timings' — marginal value over the schema, 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 (get) and resource (a video's transcript) plus the output form (plain readable text). It is clearly distinct from siblings like get_video and list_texttracks, and an agent can tell what it will receive without opening the schema.

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

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

Gives real when-to-use guidance: the stripped text is 'what you want for summarizing or repurposing,' and it names the condition for the alternative format ('Ask for format vtt to keep the timings'). It stops short of naming sibling tools or stating exclusions, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeatability profile is fully covered. The description adds the set of fields that come back, which is useful context, but says nothing about auth scope, error behavior for a missing id, or rate limits.

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

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

One front-loaded sentence with zero filler; the verb and resource lead and the field list follows compactly.

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

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

With no output schema, the description compensates by enumerating the returned fields, which is the main thing an agent would otherwise lack. Remaining gaps are minor for a single-id read tool covered by annotations.

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 single video_id parameter is documented well in the schema (numeric id, /videos/ URI, or vimeo.com URL all accepted). The description adds no syntax or format detail beyond that, 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 ("Get the full details of one video") and enumerates the payload (description, embed URL, thumbnail, privacy, tags, transcode status), which signals it is the comprehensive single-video read. It does not explicitly contrast itself with siblings like get_video_stats, get_video_privacy, or get_download_links, so an agent must infer the boundary from the word "full".

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 or when-not-to-use guidance and no named alternative. The description never says to prefer this over get_video_stats, get_video_privacy, or search_videos when a single record is already known by id.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: this is the reporting API, it needs a paid plan, and on free accounts it degrades to an explanation string rather than raising an error. That last detail meaningfully changes how the agent interprets a response, though return shape/pagination is not described.

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, metrics front-loaded and the paid-plan caveat second. No filler, no repetition of the title, every clause earns its place.

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

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

With no output schema, the description must convey what comes back, and it does by listing the four metric families. Combined with the paid-plan/free-account caveat, an agent has enough to call and interpret it, though the response format and date-range interaction are only implied.

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 the enum and date defaults, so the schema carries the parameter burden. The description's metric list loosely aligns with the 'dimension' breakdown (e.g., where views came from) but adds no formats, constraints, or semantics beyond the schema; 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?

Specific verb (get) plus resource (video analytics) with an enumeration of what is returned: views over time, unique viewers, finish rate, and view sources. The word 'real' hints at a distinction from a lighter stats tool, but it never names the sibling get_video_stats, so the agent must infer the split.

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 surfaces a real prerequisite (requires a paid plan, free accounts get an explanation rather than an error), which is useful context for when calls will succeed. However it gives no explicit when-to-use versus get_video_stats or other reporting alternatives, so routing between the two analytics-ish siblings 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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context by disclosing what the response reveals (audience permissions plus the embed domain whitelist, conditionally), which goes 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?

A single front-loaded sentence that names the resource and the most valuable payload element first, with zero 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?

With no output schema, the description must carry the return-value burden, and it does indicate the two key data points (watch permissions and the embed domain whitelist). It stops short of enumerating other privacy dimensions such as password protection or unlisted status, leaving a small gap for a one-parameter read 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% with a single documented parameter, so per the rubric the baseline is 3. The description adds no format or constraint detail for video_id beyond what the schema states.

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 pairs a specific verb ("Show") with the resource (a video's audience/embed privacy settings) and specifies the payload: who can watch, who can embed, and the domain whitelist. It is clearly distinguishable from the generic get_video sibling, though it does not explicitly name that sibling to sharpen the 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?

Usage is only implied — the phrase "exactly who can watch and embed" suggests a privacy-audit scenario, and "when embedding is restricted" hints at a conditional case. There is no explicit statement of when to call this instead of get_video or the embed-preset tools, and no prerequisites are given.

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 and openWorld, so the safety profile is covered. The description adds a genuinely new behavioral fact the annotations cannot express: this tool is available on every plan tier, while the analytics sibling requires a paid plan. It does not discuss rate limits or response shape, but the plan constraint is the meaningful extra here.

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 with no filler. The return content is front-loaded and the routing alternative follows immediately, so the most decision-relevant information comes first.

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 single-parameter read tool with no output schema, the description covers what is returned, availability constraints, and the richer alternative for time-series/geographic data. Nothing an agent needs to select or invoke 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% for the single video_id parameter, so the schema already carries the parameter documentation. The description adds no syntax, format, or ID-source detail beyond what the schema provides, making the baseline 3 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?

Names a specific verb and resource and enumerates exactly what is returned (lifetime play count, comment totals, like totals). It also explicitly contrasts itself with the sibling get_video_analytics, so an agent can distinguish the two without opening either schema.

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

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

States the condition for use ('works on every plan') and names the alternative with its own condition ('For views over time, finish rate and geography use get_video_analytics, which needs a paid plan'). Both the when and the 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the ordering behavior and the product framing ('segments on the player scrubber'), but says nothing about empty results, pagination, or permission requirements.

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 with the operation and its ordering front-loaded. The second sentence is partly decorative but does orient the agent to what a chapter represents, so it earns most of 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?

This is a simple read-only tool with no output schema, so the description should ideally hint at the returned shape (timecodes, titles, count) or the no-chapters case. What is present is adequate but leaves the agent guessing about the response structure.

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 exists and schema description coverage is 100%, so the schema already carries the burden. The description adds no format, source, or lookup detail for video_id, making the baseline 3 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 and resource ('List a video's chapters') plus an ordering guarantee ('in timecode order'), which separates it from the write siblings add_chapter/update_chapter/delete_chapter. It stops short of explicitly naming those siblings, so an agent still infers the read-vs-write split from the 'List' prefix.

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 reach for this tool versus alternatives such as get_transcript or get_video, and no prerequisites (e.g., that a valid video_id is required and what happens when a video has no chapters). Usage is implied by the name only.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a critical behavioral note that comment text is untrusted and should be summarized, not acted upon—this is valuable context beyond annotations.

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

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

Two concise sentences that are front-loaded with the core action and then immediately address the security consideration. No wasted words, though the untrusted data warning could be slightly more integrated.

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 no output schema, the description covers the essential purpose and safety warning. However, it omits pagination behavior (page, per_page), sorting (direction), and return structure—details that an agent might need, especially given the low parameter description coverage.

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

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

Schema description coverage is only 25%, with only video_id having a description ('Video id.') while page, per_page, direction, and their defaults/ranges are undocumented in both schema and description. The description adds no parameter details, leaving significant gaps.

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) and resource (comments on a video), clearly distinguishing it from sibling tools like add_comment, edit_comment, and delete_comment. The agent knows exactly what this tool does.

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

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

The description implies usage by mentioning 'comments on a video,' but provides no explicit guidance on when to use this tool versus siblings like get_transcript or get_video_stats. There are no exclusions or alternatives mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description's added value is the domain context of what a preset contains, but it says nothing about pagination or result-set size even though per_page exists.

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?

One front-loaded sentence with zero filler; the verb+resource lead and the clarifying clause follows immediately.

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

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

For a simple read-only list tool with full annotation coverage and no output schema, the description is minimally viable. Its gap is that per_page signals a paginated collection but the description never explains paging behavior or how many presets to expect.

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 0% and the single parameter (per_page) is never mentioned in the description. The schema supplies only type/default/bounds (1-100, default 25), so the description fails to compensate for the missing semantic explanation of paging.

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 your saved embed presets') and adds what the resource is ('control player colors, controls and branding'), so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling apply_embed_preset or note that this is the read-side companion to it.

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

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

No when-to-use, prerequisite, or alternative is given. The agent must infer that this is the lookup step before apply_embed_preset; the description never says so or names that 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds two genuine pieces of context beyond that: each item includes a video count, and 'folders' map to 'projects' in the API. It says nothing about pagination behavior despite page/per_page existing.

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, front-loaded with the action and result shape, with the terminology clarification second. Nothing wasted or repetitive.

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

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

For a simple list tool this covers the essentials: what is returned (folders with video counts) and the API naming quirk. With no output schema, pagination and sort semantics go unexplained, leaving a modest gap for an agent that needs to page through results.

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 0% and all four parameters (page, sort, per_page, direction) are undocumented in both schema and description. The description adds no meaning about sorting options, pagination, or defaults, so an agent gets no help beyond the raw enum values.

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 clear verb+resource (list folders) and adds the distinguishing detail that each result carries a video count, which separates it from sibling get_folder. It does not explicitly name neighbors like get_folder or list_videos, but the scope is 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives (e.g., use get_folder for a single folder's details). The agent must infer usage purely from the name and title.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds domain context ('curated playlist with its own page') but says nothing about pagination, result count, or ordering behavior, which for a paged list tool is the useful missing piece.

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, front-loaded with the core action and free of filler. The second sentence earns its place by clarifying the resource semantics, though more could be said about pagination in the same budget.

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

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

For a simple list endpoint with no output schema, the description explains what showcases are but omits all parameter/pagination behavior and any guidance on result volume. It is adequate to identify the tool but incomplete for invoking it well.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the full burden and compensates with nothing. page, per_page, sort and direction are never mentioned, so an agent gets no meaning about sorting keys or pagination semantics beyond the bare 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 (list) and resource (showcases), and usefully maps the product term to the API term ('which the API calls albums'). This distinguishes it from single-item siblings like get_showcase, though it never explicitly names an alternative.

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 no when-to-use guidance: it doesn't say to use this for browsing a collection versus get_showcase for a single album, nor when to page/sort. The existence of get_showcase, create_showcase, etc. makes routing guidance valuable and it is absent.

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, so the safety profile is covered. The description adds useful context about the content returned ('with their languages and which one is active'), but omits pagination behavior, ordering, or error conditions.

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 that states the resource and the key returned fields with zero waste. It is appropriately sized for a simple list tool with one parameter.

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 one-parameter read-only list tool with no output schema and annotations covering safety, the description is nearly complete: it identifies what is returned (languages, active track). It could still mention pagination or empty-result behavior, but no critical detail for correct invocation 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 only one parameter, so the schema already fully documents video_id. The description does not add syntax or constraints beyond noting the tracks belong to a video, 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?

The description states a clear verb+resource ('List the caption and subtitle tracks on a video') and specifies the scope. It distinguishes itself from mutation siblings like upload_texttrack/update_texttrack/delete_texttrack by its read-only listing action, but it does not explicitly name alternatives such as get_transcript or list_chapters.

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 only says what the tool does, with no explicit when-to-use guidance, prerequisites, or named alternatives. The intended usage is implied by the purpose, but there is no routing information to help an agent choose this over get_transcript or list_chapters.

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, so the safety profile is covered. The description adds value beyond those annotations by disclosing the trimmed return shape (id, name, duration, privacy, play count, folder, status) and the default sort order, which is the key behavioral fact for a list tool with no output schema.

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

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

Three short sentences, zero filler. The scope and ordering (the most important selection cue) are front-loaded, followed by return shape and the sibling pointer.

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 paginated list tool with no output schema, the description compensates by enumerating the returned fields and the default ordering, and the annotations fully cover the read-only safety profile. Nothing an agent needs 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 coverage is 100%: all five parameters, including the sort and direction enums and their defaults, are documented in the schema itself. The description's only added parameter meaning is 'newest first by default', which merely restates the sort=date/direction=desc defaults. Baseline 3 applies 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 ('List videos in your Vimeo library') plus the default ordering ('newest first by default'). It also names the sibling it is not (get_video) and what shape it returns, so an agent can distinguish it from search_videos or get_video 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?

Explicitly routes the agent: 'Use get_video for the full object on one video' defines when to pick a sibling instead of this tool. It does not mention search_videos, which is the closest alternative for filtered lookups, so the when-not coverage is incomplete but clear as far as it goes.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds meaningful non-destructive behavior: the video remains in the library, so removal only affects the showcase association.

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

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

Two sentences, front-loaded with the core action and immediately followed by the critical non-destructive clarification. 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?

For a two-parameter, idempotent, non-destructive mutation, the description plus annotations and full schema coverage give the agent enough to call it correctly. Missing only minor details such as error behavior if the video is not in the showcase.

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 documents both showcase_id and video_id. The description does not add syntax, format, or edge-case meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb, resource, and scope: 'Remove one video from a showcase.' The clarification that the video itself is untouched distinguishes it from sibling tools like delete_video while directly mapping to the showcase context.

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

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

Provides clear context: use this to detach a video from a showcase without deleting it. It does not explicitly name alternatives such as delete_video or remove_videos_from_folder, but the key distinction from deletion is 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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but they cannot express that destruction is conditional. The description resolves that ambiguity by disclosing the default is unfiling back to the main library and that delete_videos_too is permanent and irreversible — key safety context beyond the annotations. It stops short of covering permissions or side effects on the library itself.

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 with the safe default front-loaded and the destructive caveat immediately after. The only redundancy is the opening sentence largely restating the title, but nothing else 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?

For a batch mutation tool with full parameter documentation in the schema and no output schema, the description covers the essential behavioral risk (unfile vs. permanent delete) and the confirm requirement. It omits the 100-item cap and any note on what the call returns, which are minor given schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by explaining the causal link between delete_videos_too and the confirm parameter ('which is why it needs its own confirm'), which the schema documents only in isolation. It does not add syntax or format detail beyond that.

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

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

The description states a specific verb (remove), resource (videos), and container (folder), plus a batch scope implied by 'in one call.' It is clearly distinct from siblings like add_videos_to_folder and remove_video_from_showcase, which operate on different containers without the batch semantics.

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 useful in-tool guidance on when to set delete_videos_too and confirms the gating role of confirm, which is real usage direction. However, it never routes the agent against alternatives such as delete_video or add_videos_to_folder, nor states prerequisites like folder ownership, so guidance is implied rather than 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds the useful scope constraint that matching is limited to the caller's own library and to title/description text. It says nothing about pagination behavior or result shape, so the added behavioral context is modest. Note a mild tension with openWorldHint=true, though a personal video library can reasonably be read as an open data set rather than a contradiction.

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

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

Two short sentences, the scope constraint front-loaded, and zero filler. Nothing could be removed without losing information.

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

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

For a no-output-schema search tool, the description covers what is searched and where, but omits any hint about pagination of results or how matches are ranked, which matters for a tool with page/per_page parameters. Annotations carry the safety profile, so the remaining gap is not severe, but it is real.

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 only 33% – page and per_page have no descriptions, though their defaults and min/max bounds make them largely self-explanatory. The description does add real meaning for query by stating that matching happens against title and description, which the schema's bare "Search text." does not convey. 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 and resource (search videos) plus the matching scope (title and description) and the corpus it operates on (your own library). That is more precise than the title alone. It does not, however, name the sibling it competes with (list_videos for browsing), so it stops short of full sibling differentiation.

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?

"This searches your videos only, not all of Vimeo" implies when this tool is appropriate (finding your own footage by text) and rules out global Vimeo search. But no alternative is named for the adjacent case of browsing rather than querying, and no prerequisites are stated. Usage is implied, not 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds the important behavioral fact that this overwrites rather than appends, which is genuinely beyond the structured fields. It does not note auth requirements or the response shape, and it slightly understates the loss of existing tags that destructiveHint=false implies, but the overwrite disclosure is valuable.

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: purpose first, the critical overwrite caveat second, and a short downstream-benefit note third. No filler, and the most consequential constraint 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?

For a 2-parameter tool with annotations and no output schema, the description covers purpose, overwrite behavior, and the effect on search. It omits any mention of the 20-tag limit (left to the schema) and permission/error behavior, but nothing essential for correct invocation 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%: the tags parameter already documents 'full tag list to set' and that an empty array clears all tags, and video_id is documented. The description reinforces the full-list semantics but adds no syntax or format detail beyond the schema, 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 ('Replace') and resource ('a video's tags') with the exact scope of the change. It does not explicitly distinguish itself from the sibling update_video, which could also touch video metadata, so it falls just short of the top mark.

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 makes the call semantics clear ('pass the complete list') but offers no explicit when-to-use guidance or named alternative (e.g., an add-tag tool or update_video). The mention that tags feed search_videos implies context without stating an exclusion or alternative.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is covered. The description adds genuinely new context beyond those annotations: the required 'upload' OAuth scope, which an agent must know before calling.

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, zero filler, with the core action front-loaded and the auth prerequisite second. Every clause 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?

For a simple two-parameter mutation with full schema coverage and annotations covering idempotency and non-destructiveness, the description is nearly sufficient. It omits only what happens to a pre-existing custom thumbnail, which the destructive/idempotent hints largely imply.

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 (video_id, time_seconds with a 0 minimum). The phrase 'from a timecode in the video itself' reinforces the meaning of time_seconds but adds no format, unit, or bounds detail beyond the schema, 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?

The description states a specific verb (set) and resource (video's thumbnail) and adds the key qualifier that the frame is taken from a timecode inside the video itself, distinguishing it from an image-upload approach. It does not explicitly name a sibling, but no sibling tool competes for this capability, so the intent is 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?

Usage is implied by the verb+resource, and the description supplies one prerequisite (the upload scope), which is more than the MID calibration case that scored 2. However, it never states when to prefer this over alternatives or any preconditions on the video's state (e.g., processing status), so guidance remains thin.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral on top: it does not state whether unspecified fields are left untouched, whether both title and timecode can be supplied together, or whether omitting both is a no-op.

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 short sentence with no filler, and the capability is front-loaded. It is efficient, though it is a verbatim copy of the title, so it spends its one sentence restating structured metadata rather than adding new information.

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

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

For a 4-parameter mutation tool with no output schema, the description omits important context: partial-update semantics, whether at least one of title/timecode_seconds must be supplied, and what the agent should expect back. The annotations cover safety but not update behavior.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, giving a baseline of 3. The description adds no format, range, or interaction detail beyond what the schema provides (e.g. that timecode_seconds is an absolute offset rather than a delta).

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

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

The description states a specific verb ('Change') and resource ('a chapter's title'), plus the second capability of moving the timecode, so an agent knows exactly what mutation this performs. It does not, however, distinguish itself from siblings like add_chapter, delete_chapter, or list_chapters, and it merely repeats the title verbatim.

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, no mention of prerequisites (e.g. chapter must exist, video must be owned), and no routing to alternatives such as delete_chapter or add_chapter. The only hint ('chapter_id, from list_chapters') lives in the schema, not the description.

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=false, idempotent=true, destructive=false and title 'Rename a folder', so the safety profile is covered. The description adds the edit-scope auth requirement, which is genuinely useful, but says nothing about failure behavior, uniqueness of names, or what happens to existing folder contents beyond the rename.

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, the action first and the precondition second, with no filler. 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?

For a two-parameter, non-destructive, idempotent rename with full schema coverage and no output schema, the definition covers the action and the auth prerequisite. Minor gaps remain around name constraints and error semantics, but nothing essential for a correct 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 description coverage is 100% and the descriptions ('New name.', 'Folder id.') are self-explanatory, so the schema carries the burden. The description adds no syntax, format, or constraint detail beyond it; 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 ('Rename a folder'), and usefully narrows the scope of an ambiguously-named 'update_folder' to renaming only. It does not name or distinguish itself from the other folder siblings (create/delete/list/add_videos), but the verb+resource is 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?

Gives a concrete precondition: the caller needs the edit scope. That is clear usage context for an auth-gated mutation. It does not, however, state any when-not or point to an alternative for other folder modifications.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds one genuinely useful behavioral fact beyond them: 'Only the fields you pass change', i.e. PATCH semantics. It omits, however, any mention of the password requirement when privacy is set to 'password' and says nothing about failure modes.

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, scope front-loaded, and the second sentence earns its place by establishing partial-update semantics. 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 6-parameter mutation with 17% schema coverage and no output schema, the description is minimally adequate: it covers the field list and partial-update behavior but leaves the password/privacy interaction and any error or permission context unexplained.

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 only 17% — just showcase_id is documented — so the description must carry the load. It names name, description, privacy, and sort but silently omits the password parameter and gives no meaning for the two enums, leaving a functionally important parameter undocumented in both places.

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 showcase's') and enumerates the mutable fields, so an agent can separate it from update_video, update_folder, and update_chapter by resource alone. The title is an exact restatement, so the description adds no differentiation beyond the resource name.

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

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

No when-to-use guidance, no prerequisites, and no reference to alternative tools such as update_video or update_folder for other resource types. The only usage-adjacent statement is the partial-update note, which is behavioral rather than 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 readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the notable behavior that the tool can flip the default/active track, but says nothing about permissions, partial-update semantics, or whether omitted fields are left untouched.

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 listing the three mutations with zero filler. Appropriate size for a simple update tool.

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

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

Covers all three mutable semantic fields, but omits that video_id and track_id are both required to address the track and says nothing about the effect on other tracks when active is set. With annotations covering safety/idempotency and the schema covering identifiers, it is serviceable 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 coverage is 60% and covers track_id, video_id, and active; the description supplies meaning for the two undocumented fields by mapping 'rename' to name and 'change its language' to language. That is roughly baseline value over a schema that already carries the identifiers.

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 specific verbs (rename, change language, activate) against a specific resource (caption track / texttrack). An agent can distinguish this from delete_texttrack, upload_texttrack, and list_texttracks by the mutation described, though the siblings are not named 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?

No guidance on when to use this versus alternatives such as delete_texttrack or upload_texttrack, no prerequisites, and no mention that a track must already exist. The enumeration of editable fields implies the use case but nothing is stated about alternatives or exclusions.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds two important non-annotation facts: partial-update behavior and the required OAuth scope. It does not describe the response shape or error conditions.

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 are front-loaded with purpose, then behavioral detail, then the auth requirement. Every sentence earns its place and there is no redundancy.

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

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

For a six-parameter mutation tool with no output schema, the description covers purpose, partial-update semantics, and required auth scope, while annotations cover safety. It could mention what the call returns or side effects on embeds, but it is largely 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%, and the schema documents all six parameters including enum meanings. The description does not add syntax, format, or default-value details beyond what the schema already 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?

The description states a specific verb, resource, and field scope: 'Update a video's title, description or privacy.' This clearly distinguishes it from siblings like set_video_tags or set_video_thumbnail by the fields it updates, though it does not explicitly name any alternative tool.

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

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

It provides a clear prerequisite ('Needs the edit scope') and partial-update semantics ('Only the fields you pass change'), which tell the agent when this tool is appropriate. It does not name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive write. The description adds a genuine behavioral fact not present in structured fields: the required upload scope, which tells the agent about an auth prerequisite. It does not mention duplicate-language handling or reversibility, so it stops 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?

Two short sentences, zero filler, and the core action is front-loaded ahead of the auth requirement. 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?

For a 6-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, input format, and auth requirement adequately. It omits what happens if a track already exists for the language and whether the new track becomes active by default, which would round out the picture.

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 every parameter (including the captions/subtitles enum and the WebVTT format) documented in the schema itself. The description only restates that WebVTT content is supplied, adding no syntax or constraint 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?

The description uses a specific verb+resource ('Add a caption or subtitle track to a video') and names the input format (WebVTT). It implies the additive distinction from update_texttrack via 'Add', but does not explicitly name or rule out sibling operations, so it falls 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?

It gives a concrete prerequisite ('Needs the upload scope'), which is useful context for when this call will succeed. However, it offers no guidance on when to use this versus update_texttrack/delete_texttrack, nor any exclusions or alternatives, leaving usage implied rather than 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 non-readOnly, openWorld, non-idempotent, so the safety frame is set; the description adds genuinely new behavior: Vimeo pulls the file server-side, it returns immediately with a video id, transcoding continues asynchronously, and the video is not playable straight away. It also discloses the required OAuth scope, which no annotation covers.

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, each earning its place, with the mechanism and the reachability constraint front-loaded before the async and scope notes. Efficient, though the async/scope details could be tightened slightly.

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

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

For a mutation tool with no output schema, the description covers the key agent-facing concerns: server-side fetch, immediate return with a video id, deferred playability, and auth scope. Remaining gaps are the optional parameters (folder_id, privacy_view), which are partly documented in the 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 60%, and the description only reinforces the url semantics (publicly reachable from the internet, not a local path) while saying nothing about name, folder_id, description, or privacy_view. The added constraint on url is useful but only lifts one of five parameters, matching the baseline 3 for partial coverage.

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

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

States a specific verb (upload) and resource (video to Vimeo) plus the mechanism (public URL to fetch), which cleanly separates it from siblings like update_video, delete_video, or add_video_to_showcase. An agent can identify this is the creation path for a new video without opening the schema.

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

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

Gives clear context: the URL must be publicly reachable, not a local path, and notes the upload scope requirement. It does not name alternative upload paths or explicitly state when to prefer this over other video-creation siblings, so it stops short of full when/when-not guidance.

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