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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the payment model: segment-level export is free, word-level timed export (word_level:true) is a paid unlock. It also notes that DOCX/PDF are unavailable, setting correct expectations. No contradictions with 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?

Three sentences, each serving a purpose: first states core function, second adds pricing context, third clarifies missing formats. No unnecessary words or repetitions. Front-loaded with the most critical information.

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

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

For a simple export tool with strong annotations (readOnly, idempotent, non-destructive), the description covers the essential: what it exports, in which formats, with timing details, pricing nuance, and exclusions. No output schema is needed as the returned file content is implied. Completely adequate given the tool's complexity.

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 low (33%, only word_level has a description). The description compensates by listing format values (SRT, VTT, TXT, MD, JSON) and explaining word_level's cost implication. job_id is not explicitly described but is self-explanatory as the identifier of the transcript to export. Overall, adds some meaning but not comprehensive.

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 clearly states the verb 'Export' and the resource 'a finished transcript', listing specific output formats (SRT, VTT, TXT, MD, JSON). It distinguishes from siblings like 'get_transcription' (which likely returns the raw transcription object) by focusing on file export with caption timings. The mention of 'DOCX/PDF are available in the Pepys web app' further clarifies the tool's scope.

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

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

The description implies usage when a transcript is finished and a file format is needed. It provides relevant context: segment-level export is free, word-level is paid, and DOCX/PDF are not available via this tool. However, it does not explicitly state when not to use it or compare to alternatives like 'get_transcription' or 'search_transcript'.

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 indicate readOnlyHint and idempotentHint. The description adds behavioral context by specifying the unit (minutes) and the purpose (avoid running out mid-run), complementing the annotations well.

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 sentence that is front-loaded with the core action and efficiently explains purpose. No superfluous words or repetition.

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 zero-parameter, no-output-schema tool, the description fully covers what the tool does, what it returns, and why to use it. Nothing 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 tool has no parameters, so the description does not need to add parameter details. Schema coverage is 100%, and the description is clear that no inputs are required, earning a baseline of 4.

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 clearly states the tool returns remaining transcription credits in minutes, with a specific verb ('Return') and resource. It distinguishes from sibling tools by focusing on balance rather than transcription operations.

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

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

The description explicitly advises using this tool to 'check headroom before starting a large batch', providing a clear use case. It does not specify when not to use or mention alternatives, but the context is sufficient.

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 indicate read-only, idempotent, non-destructive behavior. Beyond that, the description adds polling behavior details (wait_ms and polling loop) and lists the exact data returned. No contradictions.

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, first covers purpose and fields, second covers polling guidance. No redundant words, front-loaded with key information.

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

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

For a simple fetch tool with two parameters and no output schema, the description adequately covers purpose, return data, and polling behavior. Minor gaps like error handling are acceptable given its simplicity.

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?

With 50% schema coverage, the description clarifies 'job_id' as the transcription identifier (schema only has minLength) and explains 'wait_ms' as a long-poll mechanism (schema provides defaults/max). This adds meaning beyond the schema.

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

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

The description explicitly states 'Fetch a transcription by job_id' and lists the return fields, making the purpose clear and specific. It distinguishes from sibling tools like 'list_transcriptions' and 'search_transcript' by being a direct fetch by ID.

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

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

The description gives guidance on using 'wait_ms' for long-polling and implies polling until status is 'done'. It does not explicitly compare to alternatives but provides clear usage context.

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

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

Annotations are rich: readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description confirms the read-only listing behavior but adds minimal extra context beyond the annotations. It does not contradict annotations, but it doesn't expand significantly on behavioral traits such as response format or error conditions.

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

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

The description is a single, well-structured sentence that immediately conveys the action, input, output, and purpose. Every part is necessary and efficiently communicated, with no redundant 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?

The description lists the key output fields (title, publish date, episode_guid, audio_url) and explicitly states the purpose, which is sufficient for an agent to use the tool. There is no output schema, so this fills the gap. However, it could mention ordering or pagination defaults, but it's not essential given the straightforward nature of the 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 0%, so the description must explain parameters. While 'feed_url' is implied by the description ('Given a podcast RSS feed or Apple Podcasts show URL'), the 'limit' parameter is not mentioned or explained. The description adds value for 'feed_url' but fails to cover 'limit', leaving the agent to rely solely on schema constraints (min/max/default).

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 clearly uses a specific verb ('list') and resource ('episodes'), specifies the input (podcast RSS feed or Apple Podcasts URL), and states the output fields (title, publish date, etc.). It also explains the purpose: to select which episode to transcribe, distinguishing it from sibling tools like 'transcribe_podcast_feed'.

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

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

The description explicitly states the input condition ('given a podcast RSS feed or Apple Podcasts show URL') and the intended use case ('pick exactly which one to transcribe'). While it doesn't list exclusions or alternatives, the context is clear as the sibling list includes related tools like 'transcribe_podcast_feed' and 'search_transcript', suggesting when to use this tool for selection.

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. The description adds that the tool returns specific fields (job_id, status, title, duration) and mentions 'recent' jobs, implying ordering. It does not contradict annotations, but adds only moderate behavioral context beyond them.

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, no wasted words. Every sentence adds value: first states the action and output, second states the purpose. Excellent front-loading.

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

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

For a simple list tool with good annotations, the description provides sufficient context (resource, fields, purpose). It lacks mention of pagination or ordering details, but overall is adequate given the tool's simplicity.

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%, meaning the description does not explain the 'limit' or 'status' parameters. While the schema itself provides clear definitions (e.g., default, min, max, enum), the description should add contextual meaning but does not. This is a 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 clearly states the verb 'list', the resource 'transcription jobs', and includes a specific purpose: 'so you can resume, fetch, or export an earlier result instead of re-transcribing.' It distinguishes itself from siblings like 'get_transcription' (single) and 'search_transcript' (search within content).

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

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

The description implies when to use ('instead of re-transcribing') but does not explicitly list when not to use or name alternative tools. However, the context is clear enough for an agent to decide.

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 confirm read-only and idempotent behavior; description adds that it returns timestamped segments and implies efficient partial retrieval. It does not contradict annotations but could further detail return format or pagination (e.g., max_results).

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?

Single sentence, front-loaded with key action and benefit. Every word serves a purpose, no extraneous 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?

Given 6 parameters and no output schema, description is too brief. It covers core function but omits parameter details and output structure. Adequate for basic understanding but incomplete for full agent autonomy.

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

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

Schema description coverage is only 17% (only context_segments described). Description only implies 'phrase' corresponds to the 'query' parameter. No explanation of job_id, whole_word, case_sensitive, or max_results, leaving agent unclear on how to configure search.

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?

Description clearly states it searches within a transcript for a phrase and returns matching timestamped segments. It distinguishes from siblings like 'get_transcription' (whole transcript) by specifying the focused search capability, and emphasizes use for long recordings.

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?

Description hints at when to use: 'without loading the whole transcript into context' suggests it's for targeted extraction. However, it does not explicitly state when not to use or list alternative tools like 'get_transcription', leaving some ambiguity.

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 indicate idempotency and non-read-only behavior. The description adds valuable context: 'Audio is never used to train models' and the async job model. It does not cover rate limits or cost, but the additional privacy statement compensates.

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 three well-structured sentences. Each sentence adds distinct value: purpose, input options, and privacy/async handling. No wasted words, and key information 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?

Given 11 parameters and no output schema, the description covers core aspects: purpose, inputs, async return, and privacy. It lacks detail on parameter interactions (e.g., quality vs. diarize) but references get_transcription for results, which suffices for completeness.

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?

With 91% schema coverage, the description still adds meaning beyond the schema by explaining input types (e.g., YouTube, podcast feeds) and the return format. It also clarifies the mutual exclusivity of url and file_ref.

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 clearly specifies the verb (transcribe), resource (audio/video), and output (speaker-labeled, timestamped transcript with SRT/VTT captions). It distinguishes from sibling tools by emphasizing 'hours-long' content and the specialized output format.

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

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

The description provides clear input options (file_ref or URL) and context (long-form media). It mentions the async return pattern and references get_transcription. However, it does not explicitly state when not to use this tool or compare with siblings like transcribe_podcast_feed.

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 indicate idempotent and non-destructive behavior. The description adds 'Paid capability (throughput/abuse gate)' hinting at billing/rate limits, but does not elaborate on job creation or credit consumption. With annotations covering safety, this adds some value.

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 with no wasted words. Key information is front-loaded: batch-transcribe a whole podcast feed. Efficient and well-structured.

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 mentions return of job IDs. It covers the main purpose and parameter usage adequately for a batch tool of this complexity, though could add note on error handling.

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%; description clarifies that 'latest' limits episodes, but does not explain 'diarize' or provide further semantics for 'idempotency_key' beyond schema. It partially compensates for the gap but not fully.

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 clearly states it batch-transcribes a podcast feed by fanning out episodes to individual jobs, with the option to limit to latest N episodes, and returns job IDs. This distinguishes it from sibling tools like 'transcribe' which likely handles single files.

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

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

The description implies use for whole feed batch processing, and mentions it as a paid capability. However, it does not explicitly contrast with alternatives like 'transcribe' or list tools, missing a clear 'when to use' statement.

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?

The description adds context beyond annotations by mentioning the return value (file_ref) and the storage backend requirement. Annotations already indicate non-readonly and non-destructive, and the description does not contradict them.

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

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

The description is two sentences, front-loading the core purpose and usage guideline without extraneous information. Every sentence adds value.

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 explains the return value (file_ref) and the purpose. It also mentions the storage backend requirement. It is fairly complete, though it omits failure conditions or size limits.

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

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

Although schema coverage is 100% and the description mentions the alternative between path and bytes_base64, it does not add significant meaning beyond what is already in the parameter descriptions.

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 explicitly states 'Upload local audio/video' and explains the purpose: to get a file_ref for transcribing. This clearly distinguishes it from sibling tools like transcribe and export_transcript.

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 says 'Use this when the media has no public URL', providing a clear usage context. It also mentions the requirement for the Pepys R2 storage backend. However, it does not explicitly state when not to use or list alternatives.

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