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

Annotations already declare destructiveHint and idempotentHint, so the description is not carrying the safety burden alone. It still adds real value beyond them by disclosing the blast radius — media and all derived artifacts are removed, not just the transcription record — and that the effect is irreversible.

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

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

Two sentences, no filler, and the cascade scope plus irreversibility warning are both front-loaded where an agent will read them before acting.

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 destructive endpoint with full annotation coverage and no output schema, this covers what an agent needs before calling. The remaining gap is the identity of the id argument and any async/permission behavior.

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

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

There is exactly one required parameter, id, with 0% schema description coverage. The description never clarifies whether that id identifies the transcription, the media file, or a derived artifact, leaving genuine ambiguity for a cascading delete.

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 (delete), a specific resource (transcription), and the cascade scope (its media and everything made from it). No sibling tool in the list performs deletion, so the operation is unambiguously distinct.

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 implied by the irreversible nature of the operation, but the description never states when an agent should prefer this over, say, archiving, nor any prerequisites such as ownership or permission requirements, or whether confirmation is expected.

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 and openWorldHint=true, so the safety profile is covered structurally. The description adds useful context that this reads a summary for a finished transcription and that request_summary is the fallback. It does not describe return format, status values, or failure behavior, so it adds some but not rich behavioral detail.

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

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

The description is two short sentences with no wasted wording. It front-loads the resource and status, then follows with the alternative-tool routing. Every sentence contributes to selection or usage.

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?

This is a simple read-only tool with annotations covering safety and no output schema. The description explains the resource at a high level but leaves the id parameter ambiguous and does not describe what the returned summary or status looks like. For a one-parameter read tool it is adequate but 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?

The schema has a single required id parameter with 0% description coverage, and the description never explains what id refers to. It is unclear whether id identifies the transcription, the summary, or something else. The description therefore fails to compensate for the schema's missing 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 identifies the resource as the summary of a finished transcription and also mentions its status, which is more specific than the title alone. It distinguishes this tool from request_summary by naming that sibling as the alternative when no summary exists. The only minor gap is that the retrieval verb is implied rather than stated explicitly.

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

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

The description gives a clear routing rule: use request_summary if there is no summary yet, which implies get_summary is for when one already exists. It also implies the transcription must be finished. It does not spell out error conditions or prerequisites beyond that, but the main when-to-use guidance is present.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the failure mode and its error identifier (not_ready), warns that long recordings return a lot of text, explains that from/to pull whole overlapping paragraphs, and notes that format/from/to are ignored when summaryOnly is set. This is operational context an agent cannot derive from annotations 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?

Front-loaded with the resource and format contract, then progressively narrower guidance (windowing, summaryOnly, error state) — no sentence is filler. Some clauses are dense, e.g. the parenthetical "(what the app shows)" vs "the app's Export menu makes", but each carries real meaning for format choice.

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 seven parameters, no output schema and a read-only annotation set, the description covers what is returned per format, how to bound large payloads, the summary substitution, and the not-ready case. It does not spell out the exact json segment structure beyond 'word timings and speakers', a minor gap given there is 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 coverage is already 86%, so the baseline is 3; the description earns above that by explaining intent for from/to (paragraphs overlapping a moment, e.g. a search_transcriptions match), what summaryOnly swaps in (the get_summary payload), and the format split between app-style json and export-file text.

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 opens by naming the resource returned ("The finished transcript") and immediately differentiates the four output formats: json yields segments with word timings and speakers, while txt/srt/vtt yield exported file text. That distinguishes it from a status tool like get_transcription and from get_summary without needing the schema, though the opening is a noun phrase rather than an explicit 'read the transcript of...' verb.

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

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

It gives explicit conditional guidance: pass from/to for paragraphs around a moment (naming search_transcriptions as the source of such a moment), use summaryOnly for the summary, and 'check get_transcription first' when the transcript is not ready. Both the alternative tool and the exclusion condition are stated.

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 and openWorldHint already declare this is a safe, external-facing read, so the description only needs to add context. It usefully discloses the state machine (fetching through error), but says nothing about behavior for unknown ids, unavailable metadata while still processing, or polling frequency.

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

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

One compact sentence with the resource front-loaded and the state list trailing as supporting detail. Nothing extraneous, though the sentence-fragment style is slightly terse.

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 one-parameter read tool with annotations covering the safety profile, this is close to sufficient, but with no output schema the description should say more about what 'metadata' comprises and what is returned while a transcription is still in flight.

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% and the single 'id' parameter is documented in the schema as 'The transcription id.' The description adds only the implication that the id selects a single transcription, which is marginal 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?

Names the resource precisely (one transcription's status and metadata) and enumerates the lifecycle states it can return, so it is clearly distinct from get_transcript and get_summary. The verb is implicit ('Status and metadata of...') rather than stated, but the tool name supplies it.

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 enumeration of states signals polling-until-done, but the description never says when to call this instead of list_transcriptions, get_transcript, or get_summary, nor what to do once status is 'done'.

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 this is a read-only/open-world operation. The description adds useful behavior: account scope, newest-first ordering, and cursor-based continuation, but it does not explain default status behavior or what the response contains.

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 resource and ordering, followed immediately by the pagination instruction. There is no wasted text.

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 fully documented parameters and annotations covering safety, the description covers scope, ordering, and pagination adequately. It could be slightly more complete by mentioning default filtering or the shape of the paged response, but it is sufficient to invoke the tool 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 all three parameters are already documented in the schema. The description reinforces that `cursor` comes from the previous page's `nextCursor`, but adds little beyond the schema for `limit` or `status`.

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 resource and ordering: the account's transcriptions, newest first. It implies a list operation but does not explicitly contrast itself with sibling `search_transcriptions` or explain whether it returns all statuses by default.

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 provides pagination guidance by saying to pass the previous page's `nextCursor`, which helps continuation. However, it gives no explicit guidance on when to use this tool versus `search_transcriptions` or the single-transcription getters.

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=false and destructiveHint=false; the description adds the crucial non-obvious behavior that the call is asynchronous — it returns immediately with status 'generating' rather than the finished text. It omits whether re-requesting overwrites an existing summary or what happens on a pending transcription.

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, both front-loaded with the actionable facts: what it does, that it returns immediately with a generating status, and where to read the result. No filler.

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

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

For a 3-param tool with no output schema, the asynchronous contract and the get_summary handoff cover the most important gaps. Missing are the meaning of the required id, behavior when a summary already exists, and any note on cost/latency of generation, so an agent could still invoke it incorrectly.

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 documents scene and language (67% coverage), but the only required parameter, id, has no description anywhere, and the description never clarifies what 'id' identifies (transcription vs. summary). Otherwise it adds nothing parameter-level beyond the schema, which is the expected baseline here.

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

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

States a specific verb+resource (request a summary) tied to a finished transcription, and implicitly distinguishes itself from the read-side sibling get_summary. The phrase 'or a new one' is slightly ambiguous about regeneration vs. first-time creation, which keeps it from a 5.

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

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

Explicitly routes follow-up reads to get_summary, which is the main alternative an agent would otherwise confuse with this tool. It gives clear context for use but does not state when *not* to call it (e.g. when a summary already exists and is complete).

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?

Beyond the readOnly/openWorld annotations, it discloses the search corpus (newest 500 recordings), exclusions (processing or failed ones skipped), the truncation signal ('truncated is true when there may be older ones, which are not read'), and the per-result cap of five matches with start offsets. These are non-obvious behavioral limits an agent cannot infer from the 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?

The scope statement is front-loaded and every clause carries information, but the single long sentence with stacked parentheticals reads as a run-on and takes effort to parse on first pass.

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 provided, the description still conveys the return shape (up to five matches per result, second offsets, truncated flag) plus the next step, so an agent knows both what it will get back and how to drill in. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by clarifying that the query is matched as one contiguous phrase in transcript text and should be a distinctive word or short phrase rather than a natural-language question. It conveys matching semantics the schema's 'The word or phrase.' does not.

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?

Opens with a concrete question the tool answers ('which recordings said something, and when') and specifies the matching surface: the words as one phrase in what was said, not in titles. That explicitly separates it from title/metadata-oriented siblings like list_transcriptions.

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?

Tells the agent how to phrase the input ('give a distinctive word or short phrase, not a question') and routes follow-up work to get_transcript's from/to instead of reading whole transcripts. It never explicitly states when NOT to use it (e.g., you already know the recording), so it falls short of the top band.

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 establish that this is a non-idempotent, non-destructive, open-world write. The description adds the behavior an agent actually needs: it is asynchronous, kicks off immediately, consumes account minutes, returns an id rather than the finished text, and never downloads the media. That is substantive context beyond the structured fields.

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 tight sentences, front-loaded with the action, then the accepted sources, then the workflow. Every clause carries information an agent needs; nothing is redundant with the title.

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

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

There is no output schema, so the description carries the burden of explaining the return value, and it does: a transcription object with an id plus the polling path to reach the text. Combined with the cost note and source list, an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented with meaningful detail (including the captions/minutes tradeoff and the language code format). The description adds no parameter-level information beyond the notion that the input is a link, 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?

States a specific verb and resource ("Create a transcription from a link to a video or recording") and enumerates accepted sources. It also explicitly positions itself against the sibling read tools by naming get_transcription and get_transcript as the follow-up steps, so an agent can distinguish it without opening the schema.

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

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

Gives a concrete workflow: call this, poll get_transcription until status is done, then read get_transcript. It also flags the cost model ("uses the account's minutes") and that it starts immediately. It stops short of stating when not to use it (e.g. for already-uploaded files or existing transcriptions), so it is strong but not exhaustive.

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