Samplecut

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries real weight and delivers: links expire after ~1 hour, expired cuts must be reissued, and clip_id/peaks are internal fields that must not be shown to the user. It also instructs reading widget context after in-card edits, which is behavior an agent could not infer elsewhere.

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

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

Purpose and source list are front-loaded, and each subsequent sentence carries a distinct operational rule (routing, expiry, defaults, hidden fields, widget context). It is dense but slightly long, and the widget-context sentence sits at the end where it is easiest to skim past.

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

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

For an 8-parameter, 3-required tool with an output schema, the description covers everything an agent needs: what it produces, how long it lasts, what to do on expiry, which fields to surface, and how to handle post-edit widget state.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: omitting start_sec/end_sec yields the full track, format defaults to mp3 with wav allowed, and clip_id/peaks are display-suppressed. It does not clarify the start_sec vs duration_sec vs end_sec interaction, which the schema hints at only briefly.

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 ('Cut audio') and enumerates the supported sources (YouTube, TikTok, Instagram, SoundCloud, X), plus the artifact returned (a short-lived download link). An agent can distinguish this from get_transcript or send_feedback purely from 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 routing rules: lead with download_url for cut/download requests, offer editor_url for tweaking, omit start_sec/end_sec for the full track, and ask again for a fresh cut if the link expired. It does not mention the sibling retrim_clip as the path for re-cutting an existing clip, which is a missed 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 readOnly/openWorld/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: captions only exist 'when the platform provides them', the available=false fallback, and the notable fact that no job_id is returned (unlike async job tools). It does not discuss rate limits or per-platform quirks, so 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?

Four tight sentences, front-loaded with purpose then workflow then failure mode. The only redundancy is repeating lang's BCP-47 default from the schema; otherwise every sentence earns its place.

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

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

With an output schema present, return values need not be described, yet the description still explains the available flag and the segment timing fields that drive the next call. Combined with the stated no-job_id fact and the follow-up tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all five parameters are already documented, including lang's BCP-47 default and the context/llm_model/conversation_id instructions. The description mostly restates the lang default and otherwise adds no parameter-level meaning, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Fetch timestamped captions') and enumerates the exact supported platforms. The tool is clearly a caption-retrieval step that precedes cut_audio, so an agent can distinguish it from siblings 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?

Explicitly prescribes the workflow: use segment start_sec/end_sec to pick a range, then call cut_audio with the same URL and those times. It also covers the negative case (available=false: tell the user to pick times another way, don't invent lyrics or timestamps), leaving little 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=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.

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful constraints beyond annotations: it only records feedback, should be called once, and must avoid links, names, and personal details.

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 front-loaded and compact: purpose, call timing, feedback-type guidance, and privacy constraint each appear in a clear sentence. 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?

With 10 parameters, rich schema descriptions, strong annotations, and no output schema, the description supplies what an agent needs: when to call, how to choose feedback_type, and what not to include. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by giving examples for missing_capability and clarifying task_completed as whether the user got what they wanted, plus a privacy constraint that affects summary/details content.

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: telling Samplecut's developers how the user's task went. It also frames this as feedback tied to tasks where these tools were used, which clearly distinguishes it from the audio-operation 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?

It gives explicit timing ('once after you finish or give up on a task') and concrete routing rules for feedback_type, including when to use missing_capability even if a workaround was found. The alternatives are well defined.

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