convert.express

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

Annotations only declare destructiveHint=false, so the description carries real weight here: it discloses that the artifact is publicly accessible to anyone with the link, that it is shareable externally, and that it persists only until the job expires. That visibility and lifetime context goes well beyond the annotation, though it omits whether the link is revocable.

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

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

Two tight sentences with no filler; the nature of the artifact is front-loaded and the security/lifetime caveat follows immediately. Every clause earns its place.

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 two-parameter, non-destructive tool with full schema coverage and no output schema, the description covers what the artifact is, who can see it, and how long it lives. The one gap is that it never states that a URL/link value is returned, which the caller would want to know.

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% – the schema already documents job_id (with its origin in transcribe_url/create_upload) and robot_key (auth requirement) – and the description adds no parameter meaning on top of that. 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 conveys a specific resource – a public web page of results for a completed job – which the create_share_link name frames as a created artifact, and it is clearly distinguishable from siblings like get_job or request_summary. It stops short of stating a verb ('creates a link that returns a URL'), relying on the name to supply the action.

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

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

The phrase 'results of a completed job' implies the prerequisite that the job must be finished, and 'for your user to open or send to others' hints at the use case. There is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_job for raw results.

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

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

Annotations only supply destructiveHint=false; the description carries the real behavioral burden and does so well, disclosing the two-phase flow (get upload_url, PUT the bytes to it) that is not visible anywhere in the schema or annotations. It omits operational details such as upload_url expiry, auth requirements, or POST-vs-PUT content expectations.

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 short sentences, zero filler, and the sequence of actions is front-loaded in the order the agent must execute them. Every clause earns its place.

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

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

With no output schema, the description usefully states what comes back (upload_url) and what to do with it, and the schema covers all inputs. The remaining gap is lifecycle detail — how long the URL is valid, whether robot_key must be carried forward — which a first-time caller would benefit from.

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 all 10 parameters already carry their own documentation (model default, robot_key chaining, size limit, ISO language codes). The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (upload) and outcome (returns an upload_url) plus the exact follow-up call (start_transcription). The phrase "For a file on your machine" implicitly scopes it against URL-sourced siblings like transcribe_url, so an agent can route correctly without opening a schema.

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

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

Gives a clear triggering condition (a local file) and names the next step explicitly ("then call start_transcription"). It does not, however, name the alternative to use when the media is not on the machine (e.g., transcribe_url), so the routing is implied rather than fully spelled out.

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 flag destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: precisely which artifacts are destroyed (file, transcript, other results), that the action is irreversible, and that it overrides the default 24-hour retention window. It stops short of covering auth failure modes or behavior when the job is already gone.

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 short sentences, front-loaded with the action and its scope, then the timing/irreversibility caveat. No filler; every clause carries semantics.

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 two-required-parameter destructive tool with no output schema, the description plus annotations cover what is deleted, that it cannot be undone, and how it differs from automatic expiry. Only edge-case behavior (missing/already-deleted job, permission failures) is unaddressed, which is a minor gap.

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

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

Schema description coverage is 100% — job_id's provenance and robot_key's auth role are both documented in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The description gives a specific verb (delete) plus the exact scope of what is removed — the uploaded file, the transcript and all other results — and explicitly contrasts it with the default 24-hour retention. That scope statement cleanly separates it from read-oriented siblings like get_job and list_jobs.

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 states the operative condition clearly: use this to remove results 'right away, instead of 24 hours after the last activity,' which tells the agent when immediate deletion is warranted. It does not name alternatives or state prerequisites (e.g., an in-progress job), so it falls short of a full when/when-not treatment.

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?

readOnlyHint already declares safety. The description adds valuable context about identity resolution: IP-based for anonymous use and account-based once robot_key is linked, which goes beyond annotations.

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

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

Single, dense sentence front-loads the primary output (price and free minutes) and the identity condition. No 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?

Given annotations cover safety and schema covers parameters, the description completes the call context by explaining the robot_key identity behavior. Output schema is absent, but return values (price, free minutes) are clear from the description.

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 parameter syntax is fully documented. The description adds semantic nuance about robot_key linking and identifies the identity scope, going slightly beyond the schema's description.

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

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

The description states a specific verb (pricing/estimate) and resource (transcription cost and remaining free minutes), clearly distinguishing it from siblings like start_transcription or get_service_info.

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 estimating cost before transcribing and clarifies the identity resolution (IP vs. linked user) via robot_key, but does not explicitly say when to use it versus checking service info.

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

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

Annotations only declare readOnlyHint=true, and the description adds genuinely useful behavior beyond that: the status-conditional return payloads, and specifically that a 'payment_required' status yields a preview plus a payment_url intended to be surfaced to the user. That is actionable flow context an agent could not derive from the annotation or schema.

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 compact sentences, front-loaded with the status concept and then the two branches. Minor waste and slight ambiguity in the trailing clause about summary/action_items/translations being returned 'when requested', since no such request parameter exists on this 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?

With no output schema, the description carries the burden of explaining return values and does so for the two key statuses. The trailing reference to summary/action_items/translations is underspecified (those appear to belong to sibling tools like request_summary), leaving a small gap for a read tool whose whole job is returning payloads.

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 job_id, robot_key, and the format enum (including the 'timed'/'speaker_labels' dependency) are already documented in the schema. The description only vaguely gestures at 'the chosen format', adding no syntax or constraints beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific resource (a job) and its status, and enumerates the two meaningful status outcomes ('completed', 'payment_required') with what each returns. It is distinguishable from list_jobs and delete_job, though the verb itself is implied by the name rather than stated.

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?

Usage is only implied: an agent can infer this is the polling tool after start_transcription/transcribe_url, and the payment_required branch tells it what to do next. However, it never names an alternative or states when NOT to use it (e.g., vs. list_jobs for enumerating jobs).

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, so the safety profile is covered and the bar is lower. The description adds useful content scope (free minutes, prices, limits) but says nothing about whether the info is static or live, whether it requires auth, or how large the response is. Adequate but not rich.

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 compact sentence with no filler, and the most important item (what the service does) is front-loaded. It reads as a noun-phrase fragment rather than a sentence, which is slightly less scannable but costs nothing in length.

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

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

With no parameters and no output schema, the description only needs to convey what comes back, and it does so at a topic level. It is sufficient for a zero-arg info tool, though it could note the return format (e.g., documentation text vs. structured data).

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is 100% trivially.

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 enumerates the exact payload of the tool (service overview, usage guidance, free minutes, prices, models, languages, limits), so an agent knows what it returns. It lacks a clean verb+resource phrasing like 'Get service documentation,' but the content listing is unambiguous and clearly distinct from the action-oriented siblings (transcribe_url, create_upload, etc.).

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?

Usage is only implied: the phrase 'how to use these tools' suggests consulting this before invoking siblings, and the pricing/limits content hints at cost-checking scenarios. There is no explicit when-to-use or when-not-to-use statement, and no named alternative (e.g., estimate_cost for cost questions).

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 readOnlyHint annotation already covers the safe read-only nature. The description adds useful behavioral context beyond annotations: jobs are retained only 24 hours after last activity, results are ordered newest first, and status is included. It does not discuss pagination or result-size limits, but for a simple list tool this is solid added 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?

A single compact sentence that front-loads the resource and scope, then packs in the retention rule, ordering, and returned field. 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 simple read-only list tool with a fully documented schema and readOnlyHint annotation, the description covers the essential behavior: what is listed, retention window, order, and status. It does not explain pagination or help distinguish from get_job, but there is no output schema requiring that.

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 single robot_key parameter is fully documented by the schema itself. The description adds no parameter-level meaning beyond what is already in the schema, making the baseline 3 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 names the resource ('Your jobs') and specifies scope ('still exist'), ordering ('newest first'), and included fields ('with their status'), so an agent can tell it retrieves a collection rather than a single job. However, it does not name the sibling tool get_job or otherwise explicitly differentiate itself from alternatives.

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?

There is no explicit when-to-use guidance, no conditions, and no mention of alternatives like get_job for fetching a single job. The retention note ('jobs are deleted 24 hours after the last activity') explains data lifetime but does not tell the agent when to choose this tool over 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?

Annotations only carry destructiveHint=false, so the description does the heavy lifting and discloses the key non-obvious trait: the call returns immediately (asynchronous trigger) and the artifact surfaces later in get_job under 'summary'/'action_items'. It could say more about failure modes or whether the request can be re-issued.

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 short sentences, front-loaded with the action and immediately followed by the async-result contract. Every clause carries information; nothing is padding.

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

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

With no output schema, the description correctly explains where the result appears (get_job), which is the essential return-path information for this async tool. Minor gaps remain around error/precondition behavior if the job is incomplete.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, so the baseline is 3. The description echoes the enum values and the completed-job constraint on job_id but adds no syntax or format 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?

States a specific verb and resource: requesting an AI summary or action items for a completed job. It also implicitly distinguishes itself from get_job by noting the result is read there, though it never explicitly says 'use this instead of X'.

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

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

The phrase 'of a completed job' encodes a precondition (job must be finished) and the second sentence routes the agent to get_job to retrieve the output, which is clear usage context. No explicit exclusions or alternative-selection guidance beyond that.

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

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

Annotations only supply destructiveHint=false, so the description carries most of the burden and does so well: 'A human reads every message; there is no automatic reply' tells the agent to expect no programmatic response, and the consent requirement for reply_email is a real behavioral constraint. It does not describe latency, rate limits, or confirmation behavior.

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, zero filler, and the most important fact — that a human reads it and there is no auto-reply — is placed early. The reply_email caveat comes last, where it belongs.

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

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

For a 4-parameter feedback tool with no output schema, the description covers purpose, routing, expected response behavior, and the consent rule. Combined with 100% schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by stating the condition for including reply_email ('only if your user wants an answer'), which is a usage rule the schema's terse 'only with your user's consent' only partly implies. It adds nothing for type, message, or robot_key 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?

States a specific verb (send/tell) and resource (the convert.express team) plus the exact message categories (bug, feature, question). No sibling tool covers feedback, and an agent can immediately tell this is a human-routed feedback channel rather than a job/transcription operation.

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?

Clear when-to-use context: for bugs, missing features, or questions, and explicitly 'from you or your user'. It also gives a conditional rule for reply_email. It stops short of naming exclusions or pointing to alternatives, but the scope is unambiguous.

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 idempotentHint=true and destructiveHint=false, covering safety and retry behavior. The description adds that it checks file arrival and queues the job, which is useful context, but it omits error behavior or what happens if the file is missing.

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 no wasted words. The calling condition is front-loaded, followed by the core behavior, 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 simple job-queuing tool with 100% schema coverage and annotations covering safety, the description provides sufficient context: when to call and what it does. It does not explain return values, but no output schema exists, and this is a minor gap.

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

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

Schema description coverage is 100%, so both parameters (job_id, robot_key) are fully documented in the schema. The description adds no further parameter details, making the baseline 3 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 states a specific action ('checks the file arrived and queues it') and situates it in the workflow ('after the PUT to upload_url'), which distinguishes it from siblings like create_upload or transcribe_url. It does not name alternatives explicitly, but the purpose is clear.

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 the triggering condition: 'Call after the PUT to upload_url has finished.' This is a clear prerequisite, though it does not mention when not to use it or name alternative tools for other workflows.

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 openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds important behavioral context: it returns job_id and robot_key, the job is asynchronous, and you must poll get_job. It doesn't mention rate limits or failure modes, but the core async contract is disclosed.

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 the action and source constraints, then the return contract and next step. Zero waste and every clause earns its place.

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 discloses the return values (job_id, robot_key) and the follow-up poll. The schema fully covers parameters. The only gap is that it doesn't route away from the sibling start_transcription, but for an 8-param tool with 100% schema coverage, this is nearly complete.

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 documents all 8 parameters including the model enum, language auto-detect, and robot_key grouping semantics. The description adds no parameter detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (start transcribing), resource (media file from a public link), and accepted sources (direct file link or YouTube). It distinguishes itself from siblings like start_transcription and create_upload by specifying the input is a URL.

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 says to call it to start a job, then poll get_job, which is a clear workflow instruction. It does not contrast with start_transcription or create_upload, so it doesn't reach the 5 level of naming 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?

Adds meaningful behavior beyond the sparse annotations: it is asynchronous ('Returns at once') and the output materializes in get_job under 'translations', so the agent knows not to expect the result inline. It also notes timecodes are preserved. It does not mention cost or permission implications, but the async/result-location disclosure is genuinely useful.

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

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

Two tight sentences with zero filler; the capability is front-loaded and the async/result-location note follows immediately. Every clause earns its place.

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 an async mutation with no output schema, the description covers what is translated, the completion prerequisite, and where the result surfaces, which is enough to invoke it correctly. Minor gaps like cost or failure modes remain but are not essential.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds real nuance by enumerating the translatable sources and clarifying that subtitles keep their timecodes, which explains the behavioral difference among the 'srt'/'vtt'/'timed' enum values.

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

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

States a specific verb (translate) and its resource scope (transcript, subtitles, summary, action items) plus the target (another language). It is clearly distinguishable from siblings like request_summary or start_transcription, which produce rather than translate 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?

Establishes the key prerequisite that the job must be 'completed' and the source must already exist, giving the agent clear activation context. It does not name alternatives or explicit exclusions, so it stops short of a 5.

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