FFmpeg Micro

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's a mutation tool (implied by 'Cancel'), specifies error conditions (jobs in certain states cannot be cancelled), and indicates it may return an error. This adds valuable context beyond basic functionality.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a clarifying constraint in the second. Both sentences earn their place by providing essential usage and error information without any waste, making it highly efficient.

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 the tool's moderate complexity (a mutation with error conditions), no annotations, and no output schema, the description is reasonably complete. It covers purpose, usage constraints, and behavioral traits, though it could enhance completeness by mentioning potential side effects or response formats, slightly lowering the score.

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 100% description coverage, with the 'id' parameter documented as 'Transcode job UUID to cancel'. The description does not add further meaning beyond this, such as format examples or validation rules, so it meets the baseline of 3 where 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 clearly states the specific action ('Cancel') and resource ('queued or processing transcode job'), distinguishing it from siblings like 'list_transcodes' (list) or 'transcode_video' (create). It precisely defines what the tool does without being tautological.

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 context on when to use this tool (for queued or processing jobs) and when not to use it (for completed, failed, or cancelled jobs, which return errors). However, it does not explicitly mention alternatives like 'get_transcode' for checking job status or compare with other siblings, keeping it at a 4.

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?

No annotations exist, but description discloses return value (fileUrl and probe metadata). Lacks explicit mention of side effects (e.g., finalizing upload) or idempotency, but is adequate for a confirmation step.

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, starting with the most critical information (step 2 of flow). No wasted words – every sentence adds essential context.

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 3 parameters, no output schema, and no annotations, the description fully explains the tool's role, required inputs, expected output, and how to use the result. It references sibling tools to complete the workflow picture.

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 covers all 3 parameters with descriptions (100% coverage), and the description adds clarity beyond the schema: it specifies that 'filename' must be the storage object name from request_upload_url, not the original local name, and that 'fileSize' must match the prior declaration.

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 identifies 'confirm_upload' as step 2 of a direct-upload flow, specifies the action (confirm after PUT), and differentiates it from siblings like 'request_upload_url' and downstream 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?

Explicitly states when to call (after PUTting bytes), what to use the result for (media_url for transcribe_audio or inputs[].url for transcode_video), and clarifies the filename parameter is not the local filename.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the URL is 'short-lived (10 minute)', 'signed', and 'HTTPS'. It also specifies the prerequisite condition ('job must be in `completed` status'). However, it doesn't mention potential error conditions, rate limits, or authentication requirements, which would be helpful for a complete behavioral picture.

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 efficiently structured in two sentences. The first sentence states the core purpose and key constraints. The second sentence provides crucial usage guidance by contrasting with an alternative. Every word serves a clear purpose with zero redundancy, making it easy to parse quickly.

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 tool with no annotations and no output schema, the description provides substantial context: purpose, constraints, behavioral traits, and usage guidance. It effectively explains what the tool does and when to use it. The main gap is the lack of information about return values or error conditions, which would be helpful given the absence of an output 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?

The input schema has 100% description coverage, with the single parameter 'id' clearly documented as 'Completed transcode job UUID'. The description adds no additional parameter semantics beyond what the schema provides, but it does reinforce the 'completed' status requirement which relates to parameter validity. With high schema coverage, the baseline score of 3 is appropriate.

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's purpose with specific verbs ('generate a short-lived signed HTTPS URL') and identifies the target resource ('completed transcode's output file'). It distinguishes itself from the sibling 'get_transcode' by focusing on URL generation rather than job status retrieval, and explicitly contrasts with the 'output_url' field on job objects.

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 explicit usage guidance: it specifies when to use this tool ('for a completed transcode's output file'), when not to use it (if the job is not in 'completed' status), and names a clear alternative (the 'output_url' field on job objects). It also explains why this alternative is insufficient ('gs:// URL that HTTP clients cannot fetch 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?

With no annotations provided, the description carries the full burden. It discloses that the tool fetches state, including status and output_url, which helps understand its read-only nature and output format. However, it doesn't cover behavioral aspects like error handling, rate limits, authentication needs, or whether it's idempotent, leaving gaps for a tool that queries job status.

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, efficient sentence that front-loads the core purpose ('Fetch the current state...') and includes key details like status and output_url. There is no wasted verbiage, making it highly concise and well-structured for quick understanding.

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 the tool's low complexity (1 parameter, no nested objects) and 100% schema coverage, the description is minimally adequate. However, with no annotations and no output schema, it fails to fully compensate by explaining return values beyond status and output_url, such as error responses or additional metadata, leaving the agent with incomplete context for reliable 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 description coverage is 100%, with the single parameter 'id' documented as 'Transcode job UUID'. The description adds no additional meaning beyond this, such as format examples or validation rules. Since the schema fully covers the parameter, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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 action ('Fetch') and resource ('current state of a single transcode job'), specifying it retrieves status and output_url. However, it doesn't explicitly differentiate from siblings like 'list_transcodes' (bulk retrieval) or 'transcode_and_wait' (initiation with waiting), leaving some ambiguity about when to choose this specific 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?

The description implies usage by mentioning 'by ID' and status details, suggesting it's for checking a specific job's progress. However, it lacks explicit guidance on when to use this versus alternatives like 'list_transcodes' for multiple jobs or 'transcode_and_wait' for automated completion, and doesn't mention prerequisites or exclusions.

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?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it fetches 'current state' (implying real-time status), lists possible status values (queued/processing/completed/failed), and specifies that 'output_url' is only available 'when completed'. It doesn't mention error handling, rate limits, or authentication needs, but provides substantial operational context.

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 perfectly concise with two sentences that each earn their place: the first states core functionality with key details, the second provides crucial sibling differentiation. No wasted words, and information is front-loaded with the main purpose stated immediately.

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 operation with no output schema, the description is quite complete: it explains what the tool does, when to use it, what information it returns, and how it differs from alternatives. The main gap is lack of output format details (structure of returned data beyond status/url), but given the tool's simplicity and clear purpose, this is a minor omission.

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

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

Schema description coverage is 100%, so the schema already documents the single 'id' parameter as a 'Transcribe job UUID'. The description adds minimal value beyond this by mentioning 'by ID' and that it's for jobs 'created via transcribe_audio', but doesn't provide additional format or validation details. Baseline 3 is appropriate when 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 clearly states the specific action ('Fetch the current state'), resource ('a single transcribe job'), and scope ('by ID'), including what information is retrieved ('status and output_url'). It explicitly distinguishes from sibling 'get_transcode' by specifying this is for 'SRT generation jobs created via transcribe_audio', making the purpose unambiguous and 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?

The description provides explicit guidance on when to use this tool: for checking status of 'SRT generation jobs created via transcribe_audio'. It names the alternative 'get_transcode' for similar but different jobs, and implies it should be used after job creation to monitor progress. This gives clear context for tool 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?

With no annotations provided, the description carries the full burden and does well: it discloses the URL's short-lived nature (10 minutes), the prerequisite job status ('completed'), and the intended usage (for burning captions). It lacks details on error handling or authentication needs, but covers key behavioral traits effectively.

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 the core purpose, followed by usage guidance. Every sentence adds value: the first defines the tool, the second provides context and application. No wasted words, efficiently 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 1 parameter with full schema coverage and no output schema, the description is largely complete: it explains the tool's purpose, constraints, and use case. It could mention response format or error cases, but for a simple tool, it provides sufficient context for effective agent 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 description coverage is 100%, so the schema already documents the 'id' parameter as a 'Completed transcribe job UUID'. The description adds no additional parameter details beyond this, but doesn't need to compensate as the schema is comprehensive. Baseline 3 is appropriate.

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 specific action ('Generate a short-lived signed HTTPS URL') and resource ('for a completed transcribe job's SRT file'), distinguishing it from siblings like 'get_download_url' (general download) and 'get_transcribe' (job status). It precisely defines what the tool does.

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 explicitly states when to use this tool ('The job must be in `completed` status') and provides a concrete use case ('dropped directly into a transcode's `subtitles='<url>'` filter'). This gives clear context for invocation versus alternatives like 'get_transcribe' for job status.

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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: authentication requirement ('authenticated account'), pagination behavior (defaults and limits), and filtering capabilities. It doesn't mention rate limits, error handling, or response format, but covers essential operational context.

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 front-loads the core purpose and efficiently covers key details (filters, pagination). Every word earns its place with zero redundancy or fluff.

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 read-only list tool with 5 parameters and no output schema, the description is reasonably complete. It covers authentication, filtering, and pagination. However, it lacks details on response format (e.g., structure of returned jobs) and error scenarios, which would be helpful given the absence of an output 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 description coverage is 100%, so the schema fully documents all 5 parameters. The description adds marginal value by mentioning 'optional filters for status and time range' and pagination defaults, but doesn't provide additional syntax or format details beyond what's in the schema. Baseline 3 is appropriate.

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') and resource ('transcode jobs'), specifies the scope ('for the authenticated account'), and distinguishes it from siblings like 'get_transcode' (singular) and 'transcode_and_wait' (creation). It's specific and 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?

The description implies usage for listing jobs with filters, but doesn't explicitly state when to use this tool versus alternatives like 'get_transcode' (for a single job) or 'transcode_and_wait' (for creating/processing). It provides some context but lacks clear guidance on tool selection among siblings.

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?

No annotations are provided, so the description carries full burden. It discloses the presigned URL's short-lived nature (~15 minutes), the requirement to match Content-Type, and the need for a subsequent confirmation call. This provides adequate behavioral transparency for a simple upload initiation tool.

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 sentences with no redundancy. It front-loads the primary purpose and flows logically from step to step. Every sentence provides necessary 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?

While the tool lacks an output schema, the description explains the return is a presigned URL and outlines the complete flow path to obtain a final gs:// URL. It could be slightly more explicit about the response structure (e.g., that the URL is a string).

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 baseline is 3. The description adds value by explaining that filename is used as a suffix for the storage object, contentType must match the PUT call, and fileSize max is 1.9GB. This exceeds schema documentation.

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 identifies the tool as 'Step 1 of the direct-upload flow' and specifies that it returns a short-lived presigned HTTPS URL. It distinguishes itself from sibling tools like confirm_upload by clearly defining its role.

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 context for when to use the tool (as the first step in the upload flow) and what to do after (call confirm_upload after PUT succeeds). It does not explicitly mention when not to use it, but the sequential flow is well-defined.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's polling behavior, timeout handling, and return values (final job status plus signed download URL if completed). However, it doesn't mention authentication requirements, rate limits, or error handling specifics, leaving some behavioral gaps.

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?

Perfectly concise with two sentences that each earn their place: the first explains the tool's behavior and value proposition, the second provides clear usage guidance. No wasted words, front-loaded with the most important 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 complex tool with 6 parameters, nested objects, and no output schema, the description provides good context about the tool's polling behavior and return values. However, it doesn't explain what the 'final job' object contains or provide examples of terminal states beyond naming them, leaving some gaps in understanding the complete workflow.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, but it does provide context about the tool's overall behavior with parameters (like polling with timeoutSeconds and pollIntervalSeconds). Baseline 3 is appropriate when 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 clearly states the tool's purpose with specific verbs ('creates a transcode job, polls until it reaches a terminal state') and distinguishes it from sibling tools by explaining it's a 'one-shot convenience tool' that handles polling automatically, unlike the more granular 'transcode_video' and 'get_transcode' 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?

Explicitly states when to use this tool ('when you want the full transcode in one step without managing polling yourself') and implies when not to use it (when you need to manage polling manually or use other operations like cancellation, listing, or getting download URLs separately, which are covered by sibling tools).

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the asynchronous nature ('Returns immediately with a queued job'), the need for follow-up actions, and the input constraints ('gs:// or https://'). However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions that would be helpful for a mutation tool.

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 perfectly front-loaded with the core purpose in the first sentence, followed by essential behavioral context. Both sentences earn their place by providing critical information about the tool's asynchronous nature and sibling relationships. There is zero wasted verbiage.

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 no annotations and no output schema, the description does well by explaining the asynchronous behavior and follow-up requirements. However, it could provide more context about error handling, job queuing behavior, or what 'queued job' means in practice. The completeness is good but not exhaustive for a tool that creates jobs.

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 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it mentions the input URL formats and output format but doesn't provide additional context about parameter interactions or usage patterns. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Create a video transcode job'), identifies the target system ('on FFmpeg Micro'), and specifies the resource ('one or more input videos'). It distinguishes from siblings by mentioning alternative tools for progress tracking, making the purpose explicit and 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?

The description provides explicit guidance on when to use this tool versus alternatives: it states this tool 'Returns immediately with a queued job' and explicitly names three sibling tools ('get_transcode', 'list_transcodes', 'transcode_and_wait') to use for following progress. This gives clear context for when to use this asynchronous tool versus synchronous alternatives.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool returns a queued job envelope immediately (asynchronous operation), requires polling for completion, and provides a signed SRT URL for download. It does not mention rate limits, authentication needs, or error handling, but covers the essential workflow.

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

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

The description is front-loaded with the core purpose, followed by essential usage steps and integration details. Every sentence adds value—no wasted words—and it is structured logically from initiation to result usage, making it highly efficient and easy to follow.

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 the tool's complexity (asynchronous job processing) and lack of annotations or output schema, the description does a good job explaining the workflow, polling mechanism, and result handling. It could improve by mentioning error cases or response formats, but it covers the critical aspects needed for correct usage.

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 schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add any parameter-specific semantics beyond what the schema provides, such as explaining `media_url` formats or `task` implications in more detail. Baseline 3 is appropriate as the schema handles 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 clearly states the specific action ('Generate an SRT subtitle file'), resource ('from an audio or video URL'), and method ('using Whisper'), distinguishing it from siblings like transcode tools. It precisely defines what the tool does without being vague or tautological.

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 provides usage instructions: it names the alternative tools to use for polling (`get_transcribe`) and fetching results (`get_transcribe_download`), and specifies when to use them (after job completion). It also mentions integration with `transcode` tools for burning captions, offering clear context and alternatives.

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