Slice

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

Annotations only say readOnlyHint=false, destructiveHint=true, openWorldHint=true; the description goes well beyond that with the Slice sign-in requirement on first use, the hard-coded destination (only the confirmed email on that account, never another address), the one-time-per-transcript limit, and the requirement that it be sent from the originating conversation or account. These are exactly the operational constraints an agent cannot infer, and nothing contradicts the destructive/open-world hints.

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

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

Four short sentences, each carrying a distinct constraint (eligibility, auth, destination, lifetime) with the most important gating rule front-loaded. No filler or repetition 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?

With one simple parameter, full schema coverage, and an output schema (so return values need no explanation), the description covers everything an agent needs: prerequisites, destination restriction, idempotency limit, and the negative case routing to sharing. Nothing material is missing.

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

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

Schema description coverage is 100% and the single parameter (transcription_id) is already documented in the schema as a finished transcript's ID. The description reinforces 'finished transcript' but adds no syntax, format, or sourcing 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?

Names a specific verb+resource ('email a transcript') and immediately scopes it to a finished transcript. It also implicitly separates itself from creation tools like transcribe_audio and transcription_status by requiring an already-finished transcript as input.

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

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

Gives an explicit trigger ('only when the user explicitly asks for a finished transcript to be emailed'), explicit exclusions ('Do not use to send a transcript to somebody else'), and a named alternative action ('share the results page instead'). It also states the per-transcript and per-account conditions that gate use.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false, and the description is consistent, explaining exactly what mutates (new clips are appended to the episode's clip set) and that already-found clips are skipped. It further discloses failure modes ('may find fewer than usual, or none... say so plainly') and latency ('takes about a minute; if still searching, call it again with the same focus') — context annotations cannot carry.

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

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

Front-loads the use case, then behavior, return fields, latency, and the precondition in roughly that priority order. Every sentence carries operational information — no filler or restatement of the title.

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

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

Output schema exists, yet the description still names the returned fields (number, ref, title, why it fits) at low cost, and covers preconditions, mutation semantics, latency, and the sparse-result case. 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%, so the baseline is 3; the description still adds value by clarifying the retry semantics tied to the focus parameter (call again with the same focus to wait) and framing focus as the user's own words. The target_seconds behavior is mostly documented in the schema itself, so this is additive rather than essential.

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 action (searches the episode for moments matching a topic/audience and adds them as clips), a concrete resource (episode clips), and a scope constraint (skips clips already found). The example phrasings 'clips about creativity for artists' make it immediately distinguishable from make_clips and restyle_clip.

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

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

Gives an explicit trigger ('when the user wants clips from an episode on a particular topic or for a particular audience') and an explicit precondition/exclusion ('Do not use before get_episode reports the episode ready'). It also covers the retry case: call again with the same focus while searching.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds real behavioral substance on top: the full status state machine, the fact that clip fields only appear once ready, and the fallback listing behavior. It stops short of stating pagination limits or how stale the status may be.

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

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

Four sentences, front-loaded with the trigger and the return shape, then fallback and exclusion. The enumeration of clip fields is somewhat list-heavy but each item is load-bearing for deciding whether the tool answers the user's question. No filler or restatement of the title.

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

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

An output schema exists, so return values need not be fully restated, and the annotations carry the safety profile. The description still covers triggers, exclusion, fallback behavior and the status vocabulary, leaving nothing an agent needs in order to call this correctly.

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

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

Schema coverage is 100% for the single optional episode_id, so the baseline is already 3. The description goes beyond the schema by explaining the consequence of omitting it ('With no episode_id it lists recent episodes'), which is behavior the parameter definition alone does not convey.

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

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

States a specific verb and resource ('get an episode') plus the exact artifact returned: one pipeline status from a closed set of six states, and the clip metadata once ready. It explicitly distinguishes itself from the siblings that could be confused with it, naming transcribe_audio as out of scope and pointing at get_job/transcription_status-adjacent behavior.

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?

Opens with the trigger conditions ('when the user asks how an episode is going, whether it is ready, or what clips were found'), supplies an exclusion ('Do not use for transcripts made with transcribe_audio'), and explains the no-argument fallback. It also tells the agent to prefer this live read over estimating timing, which is actionable 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 establish this as a safe, read-only, non-destructive, closed-world operation, so the bar is lower. The description still adds real behavior: the response contents (status, progress, still, and a short download link when finished) and the wait:true semantics of blocking up to ~40 seconds, which the schema only vaguely calls 'briefly'.

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

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

Four tight sentences, front-loaded with the usage condition, then inputs, then outputs, then the exclusion. No filler and nothing repeated from 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 three-parameter status tool with full schema coverage, annotations covering safety, and an output schema, the description supplies everything the agent needs: purpose, input routing, blocking behavior, and an explicit sibling exclusion.

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 nevertheless adds value beyond the schema by quantifying the wait behavior (~40 seconds) and clarifying the provenance and relationship of job_id vs clip_id, notably that clip_id resolves to that clip's latest render.

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' a 'clip job'), then immediately situates it in the user's intent: knowing whether a clip is cut or rendered, or retrieving the finished file. It also names the sibling it must not be confused with (transcribe_audio), so an agent can differentiate without opening schemas.

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

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

Explicit when-to-use (check render status or fetch finished file) plus an explicit exclusion ('Do not use for transcribe_audio jobs'). It also routes input sources precisely: job_id from make_clips/restyle_clip, or clip_id for a clip's latest render.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the lookup-by-id-or-name behavior, but its enumeration of return fields (id, name, description, preview link) duplicates what the existing output schema already provides. With annotations doing the heavy lifting, this is adequate but adds little beyond structured fields.

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

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

Three tight sentences: intent first, then behavior, then the negative routing. Every sentence earns its place, though the return-field enumeration partially duplicates the output 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 single-parameter read-only lookup with an output schema, the description covers intent, filtering behavior and alternative tools. Return values need not be explained since the output schema exists, so nothing critical 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 there is a single optional parameter already documented as 'Ids or names to look up. Default all.' The description's 'Pass styles to look up particular ones' restates the same filtering semantics without adding format, matching rules, or error behavior. Baseline 3 is correct when the schema carries the parameter meaning.

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 caption styles') and immediately frames the user intent it serves ('which caption looks they can choose from'). It also names the siblings it is not (restyle_clip, make_clips), so an agent can separate it from nearby tools 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?

Explicitly states when to use it (user wants to know available caption looks) and when not to (changing a clip), routing to two named alternatives. Nothing is left to inference.

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

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

Annotations declare the non-read-only, non-destructive profile, and the description goes beyond them by disclosing the async behavior: it returns a job per clip and requires a follow-up with get_job for the files. The prerequisite on get_episode readiness is also useful behavioral context. It stops short of describing limits or failure modes, so it is strong but not exhaustive.

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

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

Front-loaded with the use case and effect, then prerequisites and the alternative, then a brief parameter note. The sentence enumerating style, caption_size, position, hook_title, fit and background is somewhat duplicative of the schema, keeping it from a full 5.

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 render tool with an output schema and annotations already present, the description supplies everything not covered elsewhere: the get_episode precondition, the restyle_clip exclusion, and the job/get_job follow-up flow. An agent has all it needs to invoke and chain 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 the schema already documents all eight parameters including enum meanings. The description adds only the source of the clips values (numbers or refs from get_episode, refs in brackets fine) and the fact that the optional style/caption fields apply to the whole batch, which is marginal value over the structured data.

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 (cuts and renders clips) with the exact resource and effect (captions burned in, one step). It clearly distinguishes itself from restyle_clip and get_episode, so an agent can identify its role 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?

Explicit trigger ('when the user picks found clips to make'), an explicit precondition ('do not use before get_episode reports the episode ready'), and an explicit negative route to a named alternative ('do not use to change a clip that is already made (use restyle_clip)'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: it is the only route to a caption id and should be called before any dependent step. It does not discuss result volume or pagination behavior beyond the schema's limit, hence 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 primary use case and efficiently packed; the sequencing rule and the exclusion clause each earn their place. It reads slightly list-like with multiple parallel question framings, but there is no filler or redundancy.

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

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

With full schema coverage, a rich annotation set, and an output schema, the description only needs to cover selection and sequencing, which it does thoroughly. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented with type, default, and meaning. The description restates the three narrowing parameters (at_seconds, from/to range, contains) without adding semantics beyond the schema, which matches the baseline 3 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 specific verb (read) and resource (captions on a clip) and enumerates the question types it answers, making its scope concrete. It explicitly distinguishes itself from transcribe_audio output and from get_episode, so an agent can separate it from siblings without opening schemas.

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

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

It gives explicit when-to-use cases (what a clip says, on-screen moment, word/typo lookup, speaker attribution), an ordering rule (read first to obtain caption ids), narrowing strategies, and explicit when-not-to-use guidance naming the correct alternatives (transcribe_audio, get_episode).

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 but non-destructive write, so the safety profile is covered. The description adds genuinely non-obvious behavior: the change is persisted on the clip, a new render is started asynchronously (hence "follow with get_job"), and save_as_default alters defaults for future clips. It does not mention credit/cost implications or failure modes, 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?

Front-loaded with the use case, then side effects, then the persistence flag, then the exclusion — a logical order with no filler. It is somewhat long and the capability enumeration partially overlaps the schema, which keeps it from a 5.

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

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

With 9 params, 4 enums, an output schema, and annotations present, the description supplies everything else an agent needs: the async re-render workflow, the persistence side effect, the get_job follow-up, and the make_clips exclusion. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries most parameter meaning. The description adds value by translating parameters into user intent ("bigger or smaller captions", "the whole video shown instead of cropped") and clarifying that save_as_default can be sent alone to preserve the current look, which is not evident from the schema alone.

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

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

The description states a specific verb+resource (restyle an already-made clip and re-render it) and enumerates the exact dimensions that can change: caption style, caption size, caption position, hook title, and fit/background. It also names the sibling it must not be confused with (make_clips), so an agent can route correctly 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?

It gives explicit when-to-use triggers mapped to user phrasing ("bigger or smaller captions", "captions moved up or down", "the hook title turned on, off or reworded"), an explicit when-not ("Do not use for clips that have not been made yet (use make_clips)"), and the follow-up step (get_job). The save_as_default condition is also scoped to "the user wants the look kept for future clips".

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

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

Annotations only declare write-ish, non-destructive, non-open-world, which is thin. The description adds substantial context beyond them: the file is copied into Slice, transcribed and searched with no further steps; the no-file path returns an upload_url; and it states hard limits (three hours, 4.5GB) plus the audio-only template behavior. This is exactly the extra behavioral detail annotations cannot carry.

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

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

Front-loaded with the trigger condition, then the two execution modes, then the follow-up and exclusions. Five sentences, each carrying distinct routing or behavioral information; nothing is redundant with 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 4-param tool with nested file object, enum, and an output schema, the description covers the trigger, both invocation paths, size/duration limits, and next-step routing. Since an output schema exists, return-value detail is correctly omitted apart from the one return value (upload_url) the agent must act on.

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 goes further by explaining the conditional semantics of the optional `file` parameter (attached → passed directly; absent → upload_url flow) and what happens to the uploaded media, which is meaning the schema does not convey. It adds little about `target_seconds` or `content_type` beyond the already-detailed schema text, keeping it short of a 5.

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

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

The first sentence states a specific verb+resource+outcome ('turn a podcast, interview, stream or other video into short clips'), and the rest of the description names the sibling alternatives it is not (transcribe_audio) and the follow-up tool (get_episode). An agent can separate this from every sibling without opening a schema.

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

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

Explicit when-to-use ('user wants ... turned into short clips'), explicit when-not ('only wants the words as text → transcribe_audio'; 'YouTube or other web links ... not supported'), plus the sequencing instruction 'Follow with get_episode'. All three routing decisions are handed to the agent directly.

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

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

Goes well beyond the annotations by disclosing the async contract (short files finish in-call, longer ones return status "processing" plus a transcription_id), the 90-minute per-file limit, the auth/quota model (first transcript anonymous, then sign-in with 3/month shared with the website), and the return contents including speaker turns and .txt/.srt/.vtt downloads.

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 primary use case and input forms, then limits, then exclusions. It is a dense single block and somewhat long, but nearly every sentence carries actionable information; only the downloads/return detail mildly overlaps the output 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 tool with nested objects, async results, and an output schema, the description covers inputs, limits, auth, and failure/long-file behavior completely. The agent has everything needed to invoke it correctly without opening 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 100%, so the baseline is 3, but the description adds real meaning: it clarifies file is for user-attached media, url must be a direct media link rather than a web page, and it explains the wait semantics by describing when results come back finished versus return a transcription_id.

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 (speech in an audio/video file turned into text) plus concrete input modalities (attached file or direct https link) and the artifact produced (transcript with speaker turns and downloads). It is clearly distinguishable from siblings like start_episode and transcription_status, which it names 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?

Explicitly enumerates when to use (podcast, interview, lecture, meeting, voice note) and when not to use, naming the alternative tool (start_episode for clips) and the excluded inputs (web pages, YouTube/Spotify/Apple Podcasts URLs, text already in the conversation, live audio). Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the polling/retry pattern and the visibility constraint that it only answers for the conversation or Slice account that started the transcription.

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

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

Four short sentences, front-loaded with the triggering condition, then the parameter, the retry rule, the scoping caveat, and the negative case. No filler; every sentence carries distinct operational 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?

An output schema exists, so return-value documentation is not required, and the description still notes it returns the transcript text. Combined with the annotations and the workflow linkage, an agent has everything needed to poll and consume the result 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 the baseline is 3. The description goes slightly beyond the schema by tying the parameter's provenance to the workflow ('pass the transcription_id it returned'), which tells the agent where to obtain the value rather than just its type.

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 (check whether the transcript is finished / get its text) and explicitly distinguishes itself from the sibling transcribe_audio. An agent can tell exactly what this tool does and does not do 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 the exact trigger condition ('when transcribe_audio returned status "processing"'), the polling instruction ('call it again after a short wait while the status is still "processing"'), and the exclusion ('do not use to start a transcription; use transcribe_audio'). When-to-use, when-to-repeat, and the alternative are all explicit.

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