Samplecut

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

Annotations only declare the read/write/open-world profile; the description adds real operational context beyond them — links expire after about an hour and a re-request yields a fresh cut, and clip_id/peaks are internal fields that must not be surfaced to the user. Auth requirements and rate limits are still unstated, so it is not 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?

Front-loaded with the verb, sources and return artifact, then batches agent-facing instructions (link preference, expiry, hidden fields, widget re-read) into compact sentences. Every sentence carries instruction value, though the density of imperatives makes it slightly heavier than an ideal terse definition.

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

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

An output schema exists, so return-value explanation is not required, and the description still covers expiry, hidden fields, default format and full-track behavior. The one real gap is sibling routing against retrim_clip for re-cutting an existing clip, which the description does not address.

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

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

Schema coverage is 100%, so the baseline is 3, but the description does add non-schema behavior: omitting start_sec and end_sec yields the full track, and it reinforces the mp3 default with wav as the allowed alternative. It does not explain the start_sec/duration_sec/end_sec precedence, which the schema only partially clarifies.

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 (cut) and resource (audio) plus the supported source platforms and the artifact returned (a short-lived download link). It does not, however, differentiate itself from the sibling retrim_clip, which also produces clips — an agent must infer the boundary from context rather than the description.

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

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

Gives concrete when-to-do-what rules: omit start_sec/end_sec for the full track, offer editor_url when the user wants to tweak the selection, and re-read widget context after an in-card adjustment. It never names retrim_clip or states when that alternative should be preferred, so routing between the two 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 cover safety (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds real behavioral context: what happens when captions are unavailable, that no job_id is returned, and the anti-hallucination constraint. This goes well beyond the structured annotations.

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

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

Purpose is front-loaded in the first sentence, followed by the downstream workflow, the failure case, and the one param note. Every sentence carries non-redundant information with no waste.

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

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

An output schema exists, so return values need not be explained; the description still covers the sibling handoff, the unavailable-captions case, and the lang default. Complete for an agent to invoke correctly and act on the result.

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

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

Schema description coverage is 100%, so the schema already documents url, lang, context, llm_model, and conversation_id in detail. The description restates lang (BCP-47, default en) but adds nothing beyond the schema for any parameter, so baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (timestamped captions) and names the platforms it supports (YouTube, TikTok, Instagram, SoundCloud). It also implicitly distinguishes itself from cut_audio by describing the fetch-then-cut workflow.

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

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

Explicitly routes to the sibling: use segment start_sec/end_sec then call cut_audio with the same URL and times. It also covers the failure path (available is false) with concrete guidance not to invent lyrics or timestamps and to tell the user to pick times another way.

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 and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the audio is reused rather than re-extracted, and the tool is invoked from the interactive card. It stops short of saying whether the prior clip is overwritten or whether clip_id remains valid.

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 operation and its reuse-of-audio behavior front-loaded before the routing hint to cut_audio.

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

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

With an output schema present, return values need no explanation, and the description covers purpose, alternative routing, and invocation source. It leaves minor gaps about the fate of the original clip and whether the re-cut replaces or versions it, which matters for a non-read-only tool.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the conversation_id protocol and format default. The description's 'new start/end' merely restates start_sec/end_sec and adds no syntax or constraint detail 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?

States a specific verb (re-cut), resource (clip), and the resulting scope (new start/end), and explicitly distinguishes itself from the sibling cut_audio. An agent can tell it apart from cut_audio and get_transcript 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?

Names the alternative explicitly ('to cut something new, use cut_audio') and gives the invocation context ('Called by the interactive card'), so the when-to-use and when-to-use-something-else conditions are both covered.

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