Podcast post-production for an AI agent: transcribe a recording, cut fillers and pauses, clean up the voice, add licensed music that ducks under speech, set chapters and export a finished episode.
Scored across 15 tools
Tools are largely distinct, covering separate pipeline stages like import, transcribe, analyze, plan cuts, build, and export. Some overlap exists among cleanup-related tools (cast_analyze, cast_enhance_voice, cast_first_pass), but descriptions clarify their different roles and outputs.
All tools use the cast_ prefix and a consistent snake_case verb_noun (or verb) pattern, e.g. cast_import_audio, cast_get_task, cast_list_projects. No mixing of conventions.
At 15 tools, the set is on the heavy side but each tool maps to a distinct step in the podcast editing workflow (import, transcribe, analyze, plan, build, enhance, music, export, account, tasks). No redundant or filler tools are present.
The surface covers the full lifecycle from import through export, including music, account, checkout, and task polling. Minor gaps exist such as deleting or renaming library items and richer project editing beyond replace-on-build.
Licensed Mubert music for the episode. library lists tracks the user already owns — always try this first, it is free and instant; formats lists show formats (styles) to generate from; curated searches staff-picked tracks by a vibe description and returns the best match as an audio_file_id (free); generate renders a full-length track for duration_sec in a format_id (paid, credits scale with length — a quote is returned first; confirm with quote_id). Pass the resulting audio_file_id to cast_build_project as music. Cast ducks music under speech automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| query | No | curated: describe the vibe ("warm lo-fi for a calm interview") | |
| quote_id | No | ||
| format_id | No | generate: a format id from mode:"formats" (or First Pass music.format_id) | |
| record_mode | No | track | |
| duration_sec | No | generate: episode length | |
| wait_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing cost behavior ('paid, credits scale with length'), the quote/confirm (quote_id) safeguard, and free vs. paid modes. It also states a side effect the agent needs: 'Cast ducks music under speech automatically.' It doesn't cover failure/rate-limit behavior, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but every sentence earns its place, and it is front-loaded with the mode breakdown and the free-first recommendation. Slightly overloaded with mode details in one block, but no wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param, multi-mode, paid-capable mutation tool with no output schema, the description covers the mode semantics, cost model, and downstream handoff well. The main gap is undocumented params (record_mode, wait_seconds) and return shape, but the essentials for correct invocation are present.
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 43%, so the description carries weight: it explains duration_sec (episode length), format_id (from mode:'formats'), query (vibe description), and quote_id (confirm after quote). It does not clarify record_mode, wait_seconds, or maxLength/pattern constraints, so it compensates for much but not all of the 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?
The description states a specific verb and resource ('Licensed Mubert music for the episode') and, crucially, enumerates the four modes (library, formats, curated, generate) with what each does. This lets an agent distinguish the sub-operations 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 when-to-use guidance: 'always try this first, it is free and instant' for library, and 'generate' is flagged as paid with a quote-first flow. It also tells the agent the downstream step: 'Pass the resulting audio_file_id to cast_build_project as music.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs Cast's cleanup analysis on a recording: filler words (um/uh/like…), long silences, mouth clicks, background noise and mains hum. Free. Returns counts and the markers you can turn into cuts with cast_plan_cuts. Sensitivities are 0–100 (default 50). Runs as a background job; waits up to wait_seconds and otherwise returns a task_id.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ||
| detect_mouth | No | ||
| detect_noise | No | ||
| wait_seconds | No | ||
| audio_file_id | Yes | ||
| detect_fillers | No | ||
| detect_silences | No | ||
| filler_sensitivity | No | ||
| silence_sensitivity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnly/idempotent/openWorld). Description adds substantial context annotations cannot: 'Free', runs as background job, waits up to wait_seconds then returns task_id, returns counts plus markers. This is real operational guidance for an agent scheduling work and handling async responses.
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?
Roughly four short sentences, each carrying distinct payload: purpose, cost, output, parameter semantics, async behavior. Front-loaded with the core action.
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?
No output schema, yet the description states what is returned (counts and markers). Async behavior is covered. Minor gap: does not tie result consumption to cast_get_task explicitly, though task_id is named.
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%, so description must compensate. It explains sensitivity scale (0–100, default 50) and defines wait_seconds behavior and the task_id fallback. Does not cover all 9 params (e.g., language, individual detect_* toggles), leaving gaps, but the high-value semantics are present.
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: analysis of a recording returning filler/silence/noise/hum markers. Distinguishes itself from cast_transcribe (text) and cast_plan_cuts (turning markers into cuts) by naming the handoff.
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?
Describes the workflow handoff to cast_plan_cuts, indicating when this step is used. No explicit when-not or scope limits, but the pipeline position is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turns a recording + a cut list (+ optional music and chapters) into a Cast project: the voice is laid on the timeline with the cuts applied, music sits on a ducked lane, chapters are stored. Free. Returns project_id for cast_export and an editor URL the user can open to review. Pass project_id to replace an earlier build. Cuts are seconds in the ORIGINAL recording (from cast_plan_cuts / cast_first_pass). The cuts are written BOTH as timeline clips and as word-anchored transcript edits, so the user can reopen the pass in the voice editor and keep editing it as text — always hand them the editor link.
| Name | Required | Description | Default |
|---|---|---|---|
| music | No | ||
| title | Yes | ||
| voice | Yes | ||
| chapters | No | Chapter marks in ORIGINAL-recording seconds (they are remapped past the cuts) | |
| project_id | No | ||
| master_lufs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds genuine value beyond them: it notes the operation is 'Free', that passing project_id replaces an earlier build (elaborating the destructive hint), that outputs are project_id plus an editor URL, and that cuts are stored both as timeline clips and word-anchored transcript edits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core transformation, then adds practical notes on replacement, cut units, dual writing, and the editor link. It is dense but each sentence contributes operational value; nothing is 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 mutation tool with annotations and no output schema, the description covers return values (project_id, editor URL), replacement behavior, and the cut/transcript dual-write. A few less-documented params remain, but an agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17%, so the description must carry weight. It successfully clarifies the crux parameter - cuts are seconds in the ORIGINAL recording (matching cast_plan_cuts/cast_first_pass) - and explains project_id's replace semantics, but leaves master_lufs, title, and music fields largely to the schema, so significant compensation is still missing.
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?
Starts with a specific verb (Turns...into a Cast project) and enumerates the inputs (recording, cut list, music, chapters), and names siblings like cast_export, cast_plan_cuts, and cast_first_pass as upstream/downstream steps. An agent can distinguish this build step from analysis, planning, and export tools.
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?
Clearly states the inputs and that passing project_id replaces an earlier build, giving the when-to-use context. It references the upstream cut sources (cast_plan_cuts / cast_first_pass) but does not explicitly contrast when to build fresh vs. update beyond the project_id hint, so no full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a Stripe checkout URL for a paid plan (or the pricing page) to hand to the user. Agents cannot pay — give the link to the human. Use after a plan-limit or insufficient-credits error.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | Plan to check out; omit for the pricing page only | |
| cycle | No | monthly |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds operational context (returns a Stripe URL, agents cannot pay) and scoping (omit plan for pricing page), but does not mention if the URL is session-bound or its expiry, which would be useful behavioral detail 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 tightly constructed sentences, front-loaded with the primary outcome and immediately followed by critical agent constraints. 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?
Given no output schema and only two simple parameters, the description is nearly complete: it explains the return type, the human handoff requirement, and when to invoke. It could mention that the URL is ephemeral or session-specific, but the core guidance is sufficient for correct use.
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 50%, with enum values documented in the schema. The description only adds the 'omit plan for the pricing page' behavior, which is helpful but minimal. It does not clarify cycle defaults or accepted values beyond what the enum already provides.
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: 'Returns a Stripe checkout URL for a paid plan (or the pricing page)'. It clearly distinguishes itself from siblings like cast_get_account or cast_build_project, and adds a crucial non-agent-actionable boundary by saying the agent cannot pay.
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 a precise trigger: 'Use after a plan-limit or insufficient-credits error.' Also explicitly hands off the payment action to a human, removing any ambiguity about when and how an agent should invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI cleanup of a recording: speech = noise + room removal (strength subtle/medium/strong), music = keep only the voice from a mixed track, bg_music = voice + a little of the original bed. Free. Produces a NEW audio_file_id — use it as the voice source in cast_build_project (cuts planned on the original still apply: same timeline). Enhance the ORIGINAL upload, not an already-enhanced file. On the free plan an API call returns a 60-second head preview (enough to A/B it) — the full-length render is one free click in the editor, or a paid-plan API call. The response says which you got.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | speech | |
| pipeline | No | fast = noise removal; full = separation + denoise (slower, heavier) | fast |
| strength | No | medium | |
| wait_seconds | No | ||
| audio_file_id | Yes | ||
| preview_seconds | No | Process only the first N seconds; omit for the whole file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-destructive, idempotent, open-world behavior, which the description does not contradict. Beyond that, the description adds critical behavioral context: it produces a NEW audio_file_id, the free-plan API returns a 60-second head preview while the full render requires an editor click or paid plan, and the response indicates which was returned. This is rich disclosure 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?
Compact and front-loaded: the first sentence defines the tool and its modes, subsequent sentences cover return value, integration, and free-tier caveats. Every sentence earns its place with 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?
Given six parameters, three enums, no output schema, and an open-world annotation set, the description covers the essential workflow (enhance original, get new ID, use in cast_build_project), the free-plan preview limitation, and the response meaning. Nothing critical 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 33%, so the description must compensate. It explains the three kind values, the strength options (subtle/medium/strong), and implies the pipeline choice via 'noise + room removal'. It does not clarify wait_seconds or preview_seconds, but the schema partially documents preview_seconds. Overall it adds significant meaning for the primary parameters.
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 title and description state a specific verb and resource — AI cleanup of a recording — and enumerate the three modes (speech, music, bg_music) with precise semantics for each. It is clearly distinguishable from siblings like cast_import_audio or cast_build_project.
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 guidance: enhance the ORIGINAL upload, not an already-enhanced file; use the new audio_file_id as the voice source in cast_build_project; cuts planned on the original still apply. It also names the alternative path for full-length render (editor click vs paid API), leaving no ambiguity about when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renders the project (cuts, ducked music, loudness normalisation, ID3 chapters) and returns a download URL, plus the commercial-license PDFs on Plus/Max. WAV and stems are plan-gated. On the free plan the API allows 3 exports a month — exporting from the editor is free and unlimited, so when the wall hits, send the user to the project link. Waits up to wait_seconds; otherwise poll with cast_get_task {kind:"export"}.
| Name | Required | Description | Default |
|---|---|---|---|
| stems | No | ZIP with per-lane stems + master (Max plan) | |
| format | No | mp3 | |
| licenses | No | ||
| loudness | No | podcast −16 LUFS · youtube −14 · broadcast −23 · none = as mixed | podcast |
| project_id | Yes | ||
| wait_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, not idempotent). The description adds crucial context beyond that: the free-plan quota (3 exports/month vs unlimited in-editor), the plan gating on WAV and stems, and the wait-then-poll behavior. It does not describe failure modes or exactly what happens to an in-flight export if the wait expires, but on a non-destructive operation the gaps are minor.
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 what is actually rendered and returned, second sentence covering fallback and quota. No filler; every clause earns its place and the most decision-relevant fact (the free-plan wall) is highlighted.
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 write-ish operation with no output schema, the description covers return value (download URL, license PDFs), plan gating, quota, wait behavior, and fallback routing. There is nothing an agent needs in order to call it correctly that 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 33%, so the description must carry weight; it names the parameters that matter (wait_seconds, stems, format, licenses, loudness) and ties each to a behavioral consequence (plan gating, license PDFs, wait-then-poll). It adds meaning beyond the schema in the right way — mapping parameters to outcomes rather than restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — render and download the episode — and enumerates the processing pipeline (cuts, ducked music, loudness normalisation, ID3 chapters) plus the return value (download URL, license PDFs). Clearly distinguishable from siblings like cast_get_task, which it explicitly names as the polling 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?
Explicit when-to-use routing is given: it names cast_get_task {kind:"export"} as the fallback when the synchronous wait expires, and it names an in-editor alternative for the free-plan wall case with a concrete action (send the user to the project link). This is stronger than the usual when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cast's one-click edit: an LLM editor removes fillers and false starts, shortens pauses, fixes the transcript, adds chapters and picks a music bed. status shows the free 60-second preview (with a listenable before/after URL). run (paid, small) re-runs the preview when it is only "offered". apply (paid, needs a paid plan) edits the WHOLE episode and returns the cuts + chapters + music task to feed cast_build_project. Paid actions return a quote first — call again with the quote_id to confirm and spend.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | status | |
| quote_id | No | Confirm a quote returned by a previous run/apply call | |
| wait_seconds | No | ||
| audio_file_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering mutation (readOnlyHint=false) and non-idempotency, the description adds substantial behavioral context: which actions are free vs paid, which require a paid plan, that apply edits the WHOLE episode, and that paid actions return a quote requiring a second call with quote_id to spend. It does not specify what happens to the source audio or irreversibility, but for a well-annotated tool this is strong disclosure.
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 dense and front-loaded, starting with the core purpose then action semantics. It is information-rich for its length, though the run-on sentence structure for the three actions could be broken down slightly for readability.
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, multi-action tool with no output schema, the description does a good job covering the workflow, prerequisites, costs, and the confirm-with-quote_id flow, and it names the downstream sibling. It omits details about wait_seconds behavior and what apply returns precisely, but is largely complete for correct invocation.
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%, so the description must compensate. It explains the action enum values' meanings and the quote_id confirmation flow, which is valuable. However, wait_seconds and audio_file_id are not explained in the description, leaving some param semantics unaddressed despite the low schema 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?
The description states a specific verb and resource ('Cast's one-click edit') and enumerates exactly what the LLM editor does: removes fillers, shortens pauses, fixes transcript, adds chapters, picks a music bed. It also explicitly routes the output to the sibling cast_build_project, distinguishing it from other cast_* tools.
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 guidance by describing each action's purpose and condition: status for the free preview, run to re-run when the preview is only 'offered', apply for the whole episode on a paid plan. The paid workflow (quote first, then confirm with quote_id to spend) is spelled out, including the paid-plan prerequisite for apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who the token belongs to, the plan, credit balance, and this month's usage against the plan limits. Call first: it tells you what is allowed before you spend anything. Free-plan limits are halved for API/agent access.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real value beyond them by disclosing the free-plan rate-limit quirk (limits halved for API/agent access), which materially affects how an agent interprets returned usage numbers.
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 waste: identity/return contents first, then the call-ordering cue, then the plan caveat. Every sentence earns its place and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and annotations already covering the safety profile, the description fully covers what the tool returns and the one counterintuitive caveat about plan limits. Nothing needed to 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?
The input schema has zero parameters, so the baseline is 4. There is nothing to disambiguate and the description correctly implies a no-argument call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and enumerates its contents: token owner, plan, credit balance, and current-month usage against limits. Among siblings that are all action-oriented (transcribe, export, checkout), this is clearly the read-only account-status 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?
Gives an explicit call-ordering directive: 'Call first: it tells you what is allowed before you spend anything,' which tells the agent when this tool is valuable. It does not name alternatives or when-not-to-use, but no sibling competes for this role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a transcribe / enhance / music / export / first_pass_apply job by task_id. Waits up to wait_seconds for it to finish.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| task_id | Yes | ||
| wait_seconds | No | ||
| audio_file_id | No | Required for first_pass_apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the important behavioral trait that the call blocks/waits up to wait_seconds, but it does not say what happens on timeout, whether partial status is returned, or any rate-limit behavior, so it adds moderate value 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?
Two tight sentences with zero waste: the purpose and resource are front-loaded, and the wait behavior follows immediately. Nothing extraneous is included.
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, yet the description never explains what the returned status looks like, how to interpret job states, or what happens when the wait times out. For a long-running-job polling tool this leaves too much unspecified for an agent to use it confidently.
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% (audio_file_id alone has a schema description), so the description must compensate. It clarifies task_id's role and that wait_seconds is a maximum wait, but only implicitly conveys the kind enum and never mentions audio_file_id's role, leaving meaningful gaps for the required kind parameter.
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 names a specific action (get status) and resource (a job identified by task_id) and enumerates the job kinds (transcribe / enhance / music / export / first_pass_apply), so the agent knows exactly what it returns. It is clear but does not explicitly differentiate from siblings such as cast_get_transcript, so it falls 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 mention of waiting up to wait_seconds implies this is used to poll or block on a previously started job, which is useful implied usage. However, it gives no explicit when-to-use/when-not or alternative tools (e.g., versus cast_get_transcript for finished transcripts), leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The transcript as text, or as numbered words with timestamps (needed to choose cuts by word index). Use from_sec/to_sec to page through long episodes — a 60-min show is ~9,000 words.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text | |
| to_sec | No | ||
| from_sec | No | ||
| max_words | No | ||
| audio_file_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the useful scale hint (~9,000 words per 60-min show) and a paging strategy, but omits the significant behavioral fact that max_words defaults to 1500 and can silently truncate a full transcript.
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 waste; the format rationale and the paging tip are front-loaded. The opening fragment lacks a verb, slightly weakening the lead, but nothing is extraneous.
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 reasonably explains the return shapes, but it leaves real gaps for a 5-parameter tool: truncation via max_words, the paragraphs format, and the required audio_file_id. Adequate but not complete enough to call confidently.
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%, so the description must carry parameter meaning. It covers format and from_sec/to_sec partially, but never mentions max_words (or its 1500 default/5000 cap), never mentions the 'paragraphs' enum value, and never states that audio_file_id is required.
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 names the resource (transcript) and enumerates the return formats (text, numbered words with timestamps), which lets an agent tell it apart from the write-side sibling cast_transcribe. It stops short of an explicit verb or naming the sibling it contrasts with, so it is clear but not fully differentiated.
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 conditional guidance for the 'words' format ('needed to choose cuts by word index') and paging advice for long episodes, which is more than implied usage. However it never says when to prefer cast_transcribe over this tool, nor when the 'paragraphs' format applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring a recording into Cast. Pass url (public http(s) link: direct file, Dropbox/Drive share, RSS enclosure) — Cast downloads it server-side. On a local (stdio) install you may pass path to a file on this machine instead. Counts against the monthly upload minutes. Returns the audio_file_id used by every other tool.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | No | Display name; defaults to the file name | |
| path | No | Absolute path to a local audio file (stdio installs only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds real value beyond that: the download happens server-side, the call consumes monthly upload minutes (a quota constraint the agent must weigh), and it returns the audio_file_id used by all downstream tools. It does not mention duplicate/re-import behavior or failure modes, so it is 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?
Roughly three sentences, all substantive, front-loaded with the core action and the primary parameter. Every clause earns its place: source types, local-file alternative, quota cost, and return value. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter import tool with no output schema, the description covers the essentials: what it does, which input to use where, the quota cost, and what it returns. The notable gap is that the schema marks no parameters required, yet effectively one of url/path must be supplied; the description implies this but never states it explicitly, nor does it describe failure/error 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 coverage is 67%, and the weakest-documented parameter is url, which the description compensates for well by defining acceptable sources (public http(s) direct file, Dropbox/Drive share, RSS enclosure). It also clarifies the stdio-only restriction on path, which the schema states but the description reinforces in usage terms. It adds little for name beyond the schema's own "defaults to the file name" note.
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 ("Bring a recording into Cast") and immediately explains the mechanism (server-side download), which makes it distinguishable from sibling cast_add_music and from cast_transcribe/cast_analyze. An agent knows exactly what this tool accomplishes 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 routes between the two input modes: url for server-side downloads (listing direct files, Dropbox/Drive shares, RSS enclosures) and path for local stdio installs only. It also states the output is the audio_file_id consumed by every other tool, giving clear downstream context. It stops short of saying when to prefer this over cast_add_music, so no explicit exclusion/alternative is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recordings already in the user's Cast library (newest first) with ids you can pass to other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the ordering ('newest first') and library scope, which is real behavioral context, but it says nothing about the default limit or truncation behavior beyond what the schema's 'default: 20' already shows.
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 tight sentence, front-loaded with the resource and scope, with no filler. Every clause (library location, ordering, id utility) 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 one-parameter read tool with no output schema, the description covers scope and ordering but leaves the parameter's meaning and the return shape (what fields an id comes with) to inference. Adequate but with a clear gap on the limit semantics.
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 0%, so the description must compensate, and it does not. The single 'limit' parameter, with its min 1 / max 100 / default 20 bounds, is never mentioned; the description only alludes to a default of 20 indirectly via 'newest first' ordering, which does not document limit at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the user's Cast library recordings) with the ordering (newest first) and the action implied by 'List uploaded audio'. It distinguishes itself from cast_import_audio by the 'already in' framing, but it does not name that sibling directly, 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?
The phrase 'ids you can pass to other tools' implies usage context (feed an id into another tool), which is a useful hint. But there is no explicit when-to-use, no bound on the 20-item default, and no mention of how it differs from cast_import_audio or cast_list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's Cast projects (newest first) with ids for cast_export / cast_build_project.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the sort order and user scoping, but says nothing about the default page size or that results are capped, which matters for a paged list.
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; the ordering and the downstream consumers are the first things read.
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?
No output schema exists, so the description reasonably states what is returned (projects newest-first with ids). However, for a paginated list the absence of any hint about the limit parameter or result count leaves a real 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 0% and the sole parameter (limit, default 10, max 50) is undocumented in both schema and description. With one non-trivial param and no compensating text, the description leaves the agent to guess how result volume is controlled.
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?
Identifies the exact resource (the user's Cast projects), the ordering (newest first), and the payload (ids), which lets an agent distinguish this list tool from siblings like cast_list_audio. It doesn't spell out the verb, but the name/title carries 'List' and the 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?
By naming cast_export and cast_build_project as consumers of the returned ids, it implies this is the lookup step preceding those tools. It stops short of an explicit when-to-use instruction and offers no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Builds a cut list for a recording without touching audio. Sources: markers (re-runs cast_analyze with the given toggles), phrases (every occurrence of each phrase, e.g. ["you know", "sort of"]), word_ranges (inclusive indexes from cast_get_transcript format:"words"), ranges (raw seconds). Sources combine. Returns the merged cuts with the text being removed, and the resulting length — review, then pass cuts to cast_build_project.
| Name | Required | Description | Default |
|---|---|---|---|
| ranges | No | Raw seconds in the ORIGINAL recording | |
| markers | No | ||
| phrases | No | ||
| word_ranges | No | ||
| audio_file_id | Yes | ||
| exclude_ranges | No | Never cut inside these (e.g. an intro you want intact) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the bar is lower. The description nonetheless adds real context: it is a dry run that doesn't mutate audio, sources combine, and it describes its return payload (merged cuts plus text removed and resulting length), which annotations do not cover.
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 purpose, then the source enumeration, then the return/next-step. Dense but each clause carries information; the parenthetical examples earn their space by clarifying parameter format. Slightly heavy on parentheticals.
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 takes on the return-value burden and does so (merged cuts, removed text, resulting length), and it explains source-combination semantics and the downstream handoff. Minor gaps remain, such as default marker toggles and behavior when no cuts are found.
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%, so the description must compensate, and it does: it defines the four source parameters (markers, phrases, word_ranges, ranges), gives a phrase example, and anchors word_ranges to cast_get_transcript format:"words". Only exclude_ranges remains purely schema-documented (though its own schema description covers it).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Builds a cut list') and immediately scopes it as a dry run that doesn't touch audio. This cleanly separates it from its downstream sibling cast_build_project, which applies the cuts.
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 — build the list, review, then pass `cuts` to cast_build_project — and explains that the `markers` source re-runs cast_analyze, tying it to sibling behavior. It stops short of stating when to prefer a different approach, but the workflow placement is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Word-level transcript (Whisper) for an audio_file_id. Starts the job and waits up to wait_seconds; if it is still running you get a task_id to poll with cast_get_task. A finished transcript is reused, not re-run. Also triggers Cast's free "First Pass" preview in the background (see cast_first_pass).
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ISO code; omit to auto-detect | |
| wait_seconds | No | ||
| audio_file_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Good context beyond annotations: mentions it starts the job and waits, with wait_seconds, and reuses finished transcripts. Annotations cover idempotency (idempotentHint=true) and safety. However, doesn't detail rate limits, auth, or error conditions, but idempotency is already declared.
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, front-loaded with the core action, then important behavioral details. Every part is useful.
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 no output schema, the description covers key behaviors: async handling via task_id, reuse of finished transcripts, and background First Pass trigger. Missing details on return format or error handling, but sufficient for correct invocation.
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 33%, so description adds value by explaining wait_seconds behavior ('waits up to wait_seconds') and that a task_id is returned for polling. language is documented in schema. audio_file_id is implied but not explicitly described.
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: 'Word-level transcript (Whisper) for an audio_file_id.' Clearly distinguishes from cast_get_transcript and cast_first_pass by describing the generation action vs retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use it: 'if it is still running you get a task_id to poll with cast_get_task' and 'A finished transcript is reused, not re-run.' This gives clear context and routing to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
cast_add_musiccast_analyzecast_build_projectcast_checkoutcast_enhance_voicecast_exportcast_first_passcast_get_accountcast_get_taskcast_get_transcriptcast_import_audiocast_list_audiocast_list_projectscast_plan_cutscast_transcribe
Add one secure layer between your agents and this server.