Weftly

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

With no annotations provided, the description carries the full burden and excels. It discloses critical behavioral traits: polling frequency constraints (60-second wait), expected completion times (1-2 minutes for short files, 10-30 minutes for long files), return structure (status, payment_status, instructions), and error handling (auto-refunds for failed paid jobs).

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 guidelines and behavioral details. Every sentence adds value—no fluff or repetition—and it's appropriately sized for a tool with complex behavior.

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 (polling, timing, error handling) and lack of annotations/output schema, the description is highly complete. It covers purpose, usage, behavioral traits, return values, and edge cases (failures, refunds), leaving no significant gaps for an agent to operate effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema provides for the two parameters (job_id and session_token), as it focuses on behavioral context rather than parameter details.

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 ('Check the status') and resource ('transcribe or summarize job'), distinguishing it from siblings like check_session_status (which checks sessions) and download_transcript (which retrieves results). It explicitly identifies the job types it monitors.

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 it ('Poll periodically after starting a job'), when not to use it (wait at least 60 seconds between checks), and timing expectations based on file length. It also distinguishes from alternatives by specifying it's for job status, not session status or downloads.

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 describes what information is returned (session status, expiration time, job array) which is helpful, but doesn't mention error conditions, rate limits, authentication requirements, or whether this is a read-only operation (though 'check' implies non-destructive).

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 efficiently communicates the tool's function, input context, and return values. Every element serves a purpose with zero wasted words.

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 provides good coverage of what the tool does and returns. It could be more complete by addressing potential error cases or clarifying the relationship with sibling tools, but it adequately covers the core functionality.

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 fully documents the single required parameter. The description adds marginal value by specifying the token's possible origins ('from create_session, create_transcript, or create_summary'), but doesn't provide additional semantic context beyond what's in 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 clearly states the tool's purpose with specific verbs ('check the status', 'list all its jobs') and identifies the resource ('session'). It distinguishes from siblings like 'check_job_status' by focusing on session-level status rather than individual job status.

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 context by mentioning session tokens from specific creation tools ('create_session, create_transcript, or create_summary'), suggesting when this tool is appropriate. However, it doesn't explicitly state when NOT to use it or name alternatives like 'check_job_status' for job-specific queries.

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: it triggers processing after upload confirmation, returns errors for missing files or incomplete payment, and requires polling 'check_job_status' for progress tracking. This covers operational flow, error conditions, and async behavior, though it doesn't detail auth needs or rate limits explicitly.

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 highly concise and well-structured: three sentences that efficiently cover purpose, prerequisites, error conditions, and next steps. Each sentence adds critical information without redundancy, making it easy to parse and 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?

Given the tool's complexity (post-upload processing with async behavior), no annotations, and no output schema, the description does a good job of completeness. It explains the workflow, prerequisites, error cases, and follow-up actions. However, it lacks details on return values or output format, which would be helpful since there's no 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%, with both parameters ('session_token' and 'job_id') documented in the schema. The description doesn't add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't explain format or constraints for 'session_token' or 'job_id'). Baseline 3 is appropriate since the schema handles parameter documentation adequately.

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: 'Confirm the upload is done and start processing.' It specifies the verb ('confirm' and 'start processing') and resource ('upload'), but doesn't explicitly distinguish it from sibling tools like 'upload_file' or 'get_upload_url' beyond mentioning they are prerequisites. The purpose is clear but sibling differentiation is only implied through usage context.

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 guidelines: 'Call this after uploading via either upload_file or the presigned URL from get_upload_url.' It names specific alternatives ('upload_file' and 'get_upload_url') as prerequisites and directs to 'poll check_job_status to track progress' for post-invocation. This clearly indicates when to use this tool versus others in the workflow.

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 the full burden. It mentions that the tool creates a payment URL (implying a transactional operation) and specifies prerequisites ('Requires a session_token, media_type, and job_type'), which adds useful context. However, it doesn't disclose important behavioral aspects like authentication requirements, rate limits, error conditions, or what the output looks like (only mentions creating a URL but not the format).

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 states the purpose and usage guidelines, the second lists prerequisites. Every sentence adds value—no wasted words. The '[Advanced]' prefix signals complexity appropriately, and information is front-loaded with the core purpose.

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 (payment integration) and lack of annotations/output schema, the description is somewhat complete but has gaps. It covers purpose, usage context, and prerequisites well, but misses details on authentication, error handling, rate limits, and output format. For a payment-related tool with no structured safety hints, more behavioral transparency would be beneficial.

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 three parameters with their enums and descriptions. The description adds minimal value by listing the required parameters ('Requires a session_token, media_type, and job_type') but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline of 3 when schema coverage is high.

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: 'Create a Stripe checkout URL for payment.' It specifies the exact action (create) and resource (checkout URL), and distinguishes it from siblings by noting that most callers should use create_transcript or create_summary instead. This provides specific differentiation beyond just the tool name.

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: 'Only needed if you created a session manually via create_session.' It also names alternatives: 'most callers should use create_transcript or create_summary, which include checkout automatically.' This clearly defines the specific context for usage and when to choose other 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 behaviors: the tool creates an anonymous session, returns a session_token, and specifies that the token is valid for 24 hours for subsequent API calls. However, it doesn't mention potential error conditions, rate limits, or authentication requirements.

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 and well-structured in two sentences. The first sentence establishes the tool's purpose and usage guidance, while the second explains the return value and token validity. Every word earns its place with no wasted 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 zero-parameter tool with no annotations and no output schema, the description provides excellent context about what the tool does, when to use it, and what it returns. It could be slightly more complete by mentioning potential error cases or authentication requirements, but overall it's very effective 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?

The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and it adds valuable context about the tool's purpose and output without redundant parameter information.

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: 'Create an anonymous session manually' with the specific outcome 'Returns a session_token (valid 24h) for subsequent API calls.' It distinguishes this from sibling tools by explicitly mentioning that most callers should use create_transcript or create_summary instead, which handle session creation automatically.

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: 'most callers should use create_transcript or create_summary instead, which handle session creation automatically.' It clearly indicates this is an advanced option for manual session creation when the automated alternatives are not suitable.

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 and does so comprehensively. It details the multi-step process (creates session, job, payment options), pricing ($0.75 for audio, $1.25 for video), payment methods (Stripe or crypto), and workflow steps. However, it doesn't explicitly mention rate limits or error handling, keeping it from a perfect score.

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 appropriately sized and front-loaded, starting with the core purpose and key differentiators. It efficiently packs essential information into a single paragraph, though the workflow details could be slightly more streamlined to enhance 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?

Given the tool's complexity (involving payment, multi-step workflow) and lack of annotations or output schema, the description provides complete context. It explains the return values (session_token, job_id, etc.), pricing, and integration with sibling tools, making it fully self-contained for agent understanding.

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, clearly documenting the single required parameter (media_type) with enum values and file format details. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without compensating value.

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 ('get a structured text summary') and resources ('audio or video'), distinguishing it from siblings like create_transcript by emphasizing it does both summarization and transcription in one job. It explicitly lists use cases (meeting notes, episode recaps, etc.), making the purpose highly specific 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 usage guidelines, including when to use this tool ('do NOT create a transcript job first, summarize does both in one job') and when to use alternatives (e.g., download_transcript for SRT files). It outlines the full workflow and prerequisites, offering 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 so effectively. It discloses key behavioral traits: payment requirements ('Flat price per job: $0.50 for audio, $1.00 for video'), payment methods ('paid inline via Stripe or crypto'), return values ('Returns session_token, job_id, Stripe checkout URL, and MPP crypto deposit address'), and workflow steps. It doesn't mention rate limits or error handling, but covers most critical aspects for a paid service.

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 appropriately sized and front-loaded with the core purpose in the first sentence. Subsequent sentences add necessary details about payment, workflow, and returns without redundancy. It could be slightly more concise by combining some workflow steps, but every sentence earns its place by providing 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?

Given the complexity of a paid transcription service with multiple workflow steps and no output schema, the description is quite complete. It explains the purpose, payment model, return values, and workflow sequence. It doesn't explicitly describe error cases or authentication needs, but covers the most important contextual information for proper tool 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 100%, so the schema already documents the single parameter 'media_type' with its enum values and file format details. The description adds no additional parameter information beyond what's in the schema, but doesn't need to compensate since coverage is complete. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('Turn audio or video into a timestamped text transcript') and resources ('podcasts, interviews, meetings, lectures, or any spoken content'). It distinguishes from siblings by mentioning the multi-step workflow that includes payment and session creation, unlike simpler tools like 'download_transcript' or 'check_job_status'.

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 vs alternatives by detailing the entire workflow ('create job → pay → upload → complete_upload → poll check_job_status → download_transcript'), naming specific sibling tools like 'check_job_status' and 'download_transcript' as follow-up steps. It also specifies use cases ('podcasts, interviews, meetings, lectures') and payment contexts.

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's a destructive operation (deletes files), mentions automatic cleanup timing (24h), specifies what gets affected vs. unaffected, and implies storage management purpose. It doesn't cover permissions, rate limits, 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?

Three concise sentences with zero waste: first states the core action, second provides usage context, third clarifies scope boundaries. Every sentence earns its place by adding distinct 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?

For a destructive tool with no annotations and no output schema, the description is reasonably complete: covers purpose, timing context, and scope limitations. It could benefit from mentioning response format or error cases, but given the straightforward nature and good parameter coverage, it's adequate.

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 both parameters (job_id, session_token). The description doesn't add any parameter-specific meaning beyond what the schema provides, such as explaining how these IDs relate to the deletion operation.

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 ('Delete') and resource ('uploaded audio/video source file from storage'), distinguishing it from siblings like delete_transcript. It explicitly mentions what gets deleted versus what remains unaffected (transcript/summary).

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 this tool ('to free storage' before automatic cleanup) and distinguishes it from delete_transcript by noting it doesn't affect transcripts/summaries. However, it doesn't explicitly state when NOT to use it or name alternatives for related operations.

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 clearly discloses this is a destructive operation ('permanent — the transcript cannot be recovered after deletion'), which is crucial behavioral information. However, it doesn't mention authentication requirements (implied by session_token parameter), rate limits, 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?

Two sentences with zero waste: the first states the purpose, the second warns about permanence. It's front-loaded with the core action and appropriately sized for a simple deletion tool.

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 destructive tool with no annotations and no output schema, the description does well by explicitly warning about permanence. It covers the core behavioral risk but could be more complete by mentioning authentication context or what happens on success/failure. Given the simplicity (2 parameters, 100% schema coverage), it's mostly adequate.

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 both parameters (job_id and session_token). The description doesn't add any parameter-specific information beyond what's in the schema, such as format examples or relationships between parameters. 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 ('Delete') and resource ('generated transcript (SRT file) from storage'), distinguishing it from sibling tools like delete_source which targets a different resource. It provides precise information about what gets deleted.

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 context by stating the transcript is 'generated' and mentions it's 'permanent', but doesn't explicitly say when to use this tool versus alternatives like delete_source or when not to use it (e.g., if you need to preserve the transcript). No explicit alternatives or prerequisites are mentioned.

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 behavior: it downloads a summary (implying a read operation), specifies return formats ('inline' vs 'url'), mentions the availability of related data (SRT transcript via another tool), and notes prerequisites (completed job). However, it lacks details on error conditions, rate limits, or authentication specifics beyond parameter requirements.

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 three sentences: the first states the purpose and return value, the second explains parameter usage, and the third provides sibling tool context. Every sentence adds value without redundancy, making it front-loaded and appropriately sized for the tool's complexity.

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 annotations and no output schema, the description does well to cover purpose, usage, and behavioral aspects. It explains what the tool returns (structured text summary) and format options, compensating for the lack of output schema. However, it could be more complete by detailing error handling or response structure, though it's adequate for a download tool with clear parameters.

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 adds minimal value beyond the schema: it explains the 'format' parameter's purpose ('inline' for direct text, 'url' for presigned URL) and implies 'job_id' and 'session_token' are for accessing a specific job, but doesn't provide additional context like format examples or token usage details. Baseline 3 is appropriate given high 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 clearly states the specific action ('Download the summary for a completed summarize job') and resource ('summary'), distinguishing it from sibling tools like 'download_transcript' which handles transcripts. It explicitly mentions what the tool does and what it returns.

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 completed summarize jobs) and mentions an alternative ('download_transcript') for accessing transcripts from the same job, with a clear distinction that no separate transcription job is needed. It also specifies format options and their use cases.

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 for behavioral disclosure. It effectively describes key behaviors: the tool downloads transcripts (implying a read operation), requires completion status as a prerequisite, and offers multiple format options with specific use cases. It doesn't mention error conditions, rate limits, or authentication details beyond the session_token parameter, but covers the core operational behavior adequately.

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 states the purpose and format options with usage guidance, the second provides the critical prerequisite condition. Every element serves a clear purpose with zero wasted words, and the most important information (what the tool does) 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?

For a tool with 3 parameters, 100% schema coverage, no annotations, and no output schema, the description provides excellent context about prerequisites, format semantics, and usage scenarios. It doesn't describe the return value structure (which would be helpful since there's no output schema), but otherwise gives the agent sufficient information to use the tool correctly in context with its siblings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the semantic meaning of each format option with concrete use cases (e.g., 'srt for subtitle workflows', 'json for programmatic access'), which goes beyond the schema's technical enum definitions. This helps the agent make informed parameter choices based on the user's actual needs.

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 the verb 'download' and resource 'transcript for a completed transcribe or summarize job', making the purpose specific and clear. It distinguishes this tool from sibling tools like 'download_summary' by focusing on transcripts rather than summaries, and from 'check_job_status' by being an action rather than a status check.

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: 'once check_job_status returns status "completed"'. It also distinguishes usage scenarios for different formats (e.g., 'use for subtitle workflows', 'use for LLM context'), helping the agent choose appropriate parameters. No explicit exclusions are stated, but the prerequisite condition serves as a clear usage boundary.

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 discloses key behavioral traits: file size limits (audio up to 2GB, video up to 5GB), prerequisite payment status, error handling for unpaid cases, and the need for a follow-up action (complete_upload). It lacks details on rate limits or authentication nuances beyond session_token.

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 constraints and workflow steps in three efficient sentences. Each sentence adds essential information without redundancy, making it highly concise 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 annotations and no output schema, the description provides strong context for a tool with 2 parameters and 100% schema coverage. It covers purpose, constraints, prerequisites, and next steps, but lacks details on the URL format or response structure, leaving minor gaps.

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 both parameters (job_id and session_token). The description does not add any parameter-specific details beyond what the schema provides, such as format examples or constraints, meeting the baseline for high 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 clearly states the specific action ('Get a presigned URL to upload a file via HTTP PUT') and resource ('file'), distinguishing it from sibling tools like 'upload_file' by focusing on URL generation rather than direct file transfer.

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 ('Payment must be completed first') and when not to use ('returns an error if unpaid'), and provides a clear alternative sequence ('After uploading, call complete_upload to start processing'), guiding the agent through the workflow.

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 traits: the base64 encoding method, size limits, performance implications ('base64 triples the payload size'), error conditions ('returns an error with the current payment_status if unpaid'), and required follow-up action ('call complete_upload to start processing'). However, it lacks details on rate limits or authentication beyond the session_token parameter.

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 and efficiently structured into four sentences, each adding critical information without waste: method and limits, alternative for large files, payment requirement, and post-upload step. It avoids redundancy and maintains clarity throughout.

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 complexity of a file upload tool with no annotations and no output schema, the description is largely complete. It covers purpose, usage guidelines, behavioral traits, and next steps. However, it does not describe the return values or error formats, which could be useful for an agent, leaving a minor gap in 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add specific meaning to individual parameters beyond implying that 'session_token' is needed for authentication and 'job_id' relates to a job, but this is minimal additional value. The baseline score of 3 is appropriate as the schema handles most of the parameter 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 states the specific action ('Upload a file directly via base64 encoding') and resource ('file'), distinguishing it from sibling tools like 'get_upload_url' which uses a different method. It specifies supported file types (audio, video) and size limits, 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 (for files up to 2GB audio/5GB video) and when not to use it (for files larger than 10MB, prefer 'get_upload_url + HTTP PUT'), naming the alternative. It also states prerequisites ('Payment must be completed first') and next steps ('After uploading, call complete_upload'), offering comprehensive usage context.

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