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

With no annotations, the description carries the full burden, and it does disclose real traits: the operation is a queueing/mutation, it is deliberately non-recursive (with the rationale about backup directories), and already-transcribed files are reused rather than re-queued. It does not mention permissions, cost/rate limits, or failure handling for partially bad folders.

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 core action, and the rationale sentences (non-recursion, reuse) each earn their place by changing agent behavior. The prose is slightly padded with em-dash asides, but nothing is redundant.

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?

An output schema exists, so not describing the returned job_ids is acceptable, and the description does tell the agent how to consume them. However, for a 4-parameter batch mutation with 0% schema coverage, the undocumented limit/pattern/language parameters and the unaddressed interaction between 'every media file' and pattern filtering leave real 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 0% and the description explains only one of four parameters ('folder must be absolute'). The semantics of limit, pattern, and language — notably that pattern defaults to '*' and can narrow what 'every media file' actually means — are left entirely undocumented in both schema and prose.

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 ('Queue every media file in a folder, one job each') along with the batch granularity — one job per file — so the agent immediately distinguishes this from transcript_create (single file) and transcript_list. The scope constraint (''folder' must be absolute') further pins the operation down.

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 the agent to follow-up tools: poll job_ids with transcript_status or watch the set with transcript_list. What's missing is a 'when not' clause — nothing tells the agent to prefer transcript_create for a single file, which is the most likely sibling confusion given the tool name.

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, the description carries the full behavioral burden and does so well: it distinguishes queued (immediate) from running (chunk-boundary, up to ~2 minutes) jobs and guarantees that already-transcribed content survives and is resumable. It omits auth/permission requirements, which keeps it short of a 5.

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 short, front-loaded sentences with no filler; the primary action leads and timing/data-safety details follow. Size is well matched to the operation'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?

An output schema exists, so return values need not be described, and the behavioral narrative is solid. The remaining gaps are the undocumented job_id parameter and the absence of any auth or prerequisite context.

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 single required parameter job_id has 0% schema description coverage, and the description never mentions it or its expected format/source. Unlike the zero-parameter baseline case, here the description leaves the one parameter entirely undocumented.

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 with a specific verb+resource pair ('Stop a job'), which is better than a tautology. However, 'job' is never identified as a transcription job, and there is no differentiation from the sibling transcript_delete, which an agent could reasonably confuse with cancellation.

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 rather than stated: the note that 'the job can be resumed later' implicitly contrasts cancellation with the destructive transcript_delete, but no alternative is named and no explicit when-to-use or when-not-to-use condition is given.

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 and does so well: it discloses the async/non-blocking behavior, the cache-bypass semantics of force, the 4-hour source limit, the auth_required failure mode and the exact env vars (TRANSCRIPTOR_COOKIES_FROM_BROWSER/FILE) needed to work around it. This is far more than the schema conveys.

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?

Though multi-paragraph, it is front-loaded with the core behavior first and then parameter semantics, and every sentence adds operational value that the 0%-covered schema and absent annotations leave unstated. No filler or restatement of the name.

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?

An output schema exists, so the description needn't detail return shape, yet it still notes that the result reports origin. Combined with the failure modes, limits, follow-up calls, and per-parameter semantics, an agent has everything needed to invoke this 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 0%, so the description must fully compensate, and it does: source (absolute path/expanded ~ vs URL, yt-dlp coverage, direct media URLs), captions (manual_only/prefer/never tradeoffs and the reported origin), language (ISO code, omit for auto-detect), and force (bypasses cache) are all explained with meaning beyond the bare types.

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 precise verb+resource and its synchronous contract: 'Start a transcription job and return its id immediately.' It also implicitly distinguishes itself from the polling/read siblings it names (transcript_status, transcript_get), so an agent knows this is the initiation call, not the retrieval call.

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 tells the agent how to proceed after calling ('Poll transcript_status, and read partial output with transcript_get while it runs'), names the alternatives for the follow-up work, and states refusal conditions (relative paths, playlists/channels, >4h sources) with the retry path for auth-walled URLs.

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, the description carries the full burden and does it well: it declares destructiveness, irreversibility, the exact cascade of deleted objects, the extra on-disk effect of delete_media=True, and the runtime precondition failure mode. This is far beyond what a bare 'delete' implies.

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

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

Four short sentences, front-loaded with the destructive/non-reversible warning, then consequences, then the parameter caveat, then the precondition. No sentence is 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?

An output schema exists, so return values need no explanation. For a destructive mutation tool with zero annotation coverage, the description covers impact scope, side effects, and the precondition that would otherwise cause a failed call — nothing an agent needs 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 description coverage is 0%, so the description must compensate. It fully explains the non-obvious parameter (`delete_media=True` also removes scratch audio on disk) and its default sense of being opt-in; job_id is self-evident, so nothing material is left ambiguous.

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 ('Delete a transcript') and immediately scopes it by enumerating exactly what is removed: the job, its segments, chunks, events and cached renders. This clearly separates it from sibling read tools (transcript_get, transcript_list) and from transcript_cancel, which it explicitly defers to.

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 an explicit when-not condition and the alternative action: 'Refuses while the job is running — cancel it first.' An agent knows to route to the cancel path first rather than attempting the delete and failing.

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, the description carries the full burden and does well: it discloses that this is the only disk-writing operation, that it happens only on request, that dest_path must be absolute, and that the write is atomic ('nothing partial is left behind'). It omits whether an existing file at dest_path is overwritten and what permissions/auth are required, which are material gaps for a mutation tool.

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

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

Three tight paragraphs, front-loaded with the action, then the write semantics, then the response-handling guidance. The markdown-vs-code-block styling advice is somewhat peripheral but earns its place by instructing the agent on output formatting.

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?

An output schema exists, so return values needn't be re-explained, yet the description usefully flags download_urls and view_url. Combined with the atomicity note and absolute-path constraint, this is nearly complete; only overwrite behavior and any permission requirements are missing for a disk-writing tool.

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

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

Schema coverage is 0%, so the description must compensate for all three parameters. It adds real meaning for dest_path (absolute requirement) but says nothing about the `format` parameter or its srt default, and nothing about job_id. Partial compensation only.

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 ('Write a transcript to a file at a path you choose') and immediately distinguishes itself from the read-style siblings ('The only thing Transcriptor writes to disk'). An agent can tell this apart from transcript_get or transcript_list without opening any 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?

Explicitly routes the agent: use this when a file path is wanted, and if the user asked for a link, hand them the download_urls/view_url instead of writing a file. It names the condition that selects each path, which is exactly the when/when-not guidance the dimension asks for.

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, the description carries the full burden and does well: it discloses the scoring heuristic, the sentence-boundary constraint, non-overlap, and critically that returned ffmpeg/crop commands are returned rather than executed and that nothing is written to disk. It omits auth requirements, rate limits, and failure modes, which keeps it short of a 5.

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 core purpose, then constraints, then return contents, then the critical 'commands are returned, not run' caveat. Four sentences with little waste; the parenthetical clarification about mid-clause moments is the only slightly verbose passage.

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?

An output schema exists, so the description need not enumerate return fields, yet the parameter side is entirely uncovered and the dest_dir/'nothing written to disk' tension is left unresolved. For a 5-parameter tool with no annotations and no schema descriptions, this leaves real gaps for an agent to guess at.

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

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

Schema description coverage is 0% for all five parameters. The description never explains count, min_s, max_s, or dest_dir; the dest_dir parameter is especially ambiguous given the claim that 'nothing is written to disk', yet the description does not reconcile this. Only job_id's role is inferable from context.

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 ('Find self-contained, high-density moments worth cutting into clips') and immediately defines the selection criteria (words per second, sentence-boundary alignment, non-overlap). This is clearly distinct from sibling operations like transcript_search or transcript_segments, which do not produce clip candidates.

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 criteria for what counts as a clip (sentence-bounded, dense, non-overlapping) is spelled out, which implies when the tool is appropriate. However, there is no explicit when-to-use versus alternatives such as transcript_search, and no mention of prerequisites (e.g. that job_id must reference a completed transcription job).

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, the description carries the full burden and does well: it discloses the preview/full default rationale, the flooding risk, the presence of download_urls/view_url, and that running jobs return committed text with partial:true. It omits auth/permission requirements and any rate-limit or error 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?

Front-loads purpose, then format/mode, then the download_urls recommendation, then the running-job caveat. Mostly efficient, though the mode paragraph re-states its rationale ('the default exists to stop unprompted flooding, not to refuse a direct request') at slight 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?

An output schema exists so return values need not be spelled out, yet the description usefully flags download_urls, view_url and partial:true. The only real gap for a 4-parameter tool is the undocumented max_chars, which matters given 0% schema coverage.

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 0%, so the description must compensate. It documents format (txt/srt/vtt/json) and mode (preview/full), but leaves max_chars and job_id unexplained, so half the parameters remain undocumented in both schema and prose.

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 ('Transcript text, rendered from segments on demand'), which implicitly separates it from transcript_segments (raw segments) and transcript_export. However, it never names a sibling tool to route the agent, so differentiation from the 12 sibling tools rests on inference.

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 clear when/when-not guidance for mode: preview is the deliberate default to avoid context flooding, full is for a direct whole-transcript request, and download_urls are recommended for long transcripts. It stops short of naming the alternative siblings (e.g., transcript_export) that would make the routing fully explicit.

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, the description carries the full burden and discloses key behaviors: it is a database-and-memory read (implying read-only), memory numbers come from the monitor task's most recent sample rather than being measured inline, and vram keys appear only on discrete GPUs. It could go further by explicitly stating no side effects or permission requirements, but it is substantially transparent.

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 a compact list of what it reports, followed by focused explanations of engine/device differences, vram behavior, viewer errors, and memory sampling. Some return-value detail may be redundant with the existing output schema, but the interpretive context largely 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 the output schema exists and there are no input parameters, the description is complete enough for correct invocation. It explains the health report's contents, usage context, and hardware-dependent variations. It could mention sibling alternatives, but no critical information is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not need to add parameter semantics, and it correctly focuses on output and behavior instead.

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 specific health aspects it reports—engine state, memory pressure, queue depth, degraded tasks, viewer status—and clarifies what engine/device mean. It clearly distinguishes the tool's diagnostic scope, but does not explicitly contrast it with sibling tools like transcript_status, so it falls short of 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?

It gives a clear when-to-use scenario: 'Worth reading before promising a user how long something will take.' This is explicit context rather than implied usage. However, it names no alternatives and no exclusions, so it does not reach 5.

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 usefully discloses ordering ('newest first'), which the schema does not express, and clarifies the semantic intent of the status filter. However it omits pagination/result-cap behavior, authentication or workspace scoping, and whether all jobs are returned by default.

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 core behavior and with no filler. The long status enumeration is verbose but is the highest-value information in the description, so it earns its space.

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?

An output schema exists, so return values need not be explained. Still, for a three-parameter list tool with zero schema coverage and no annotations, the description leaves the `query` filter and the `limit` behavior unexplained, which is a meaningful gap for an agent deciding how to call it.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It does enumerate the allowed `status` values (queued, running, paused, done, failed, cancelled, interrupted), which the schema lacks entirely, but it says nothing about `limit` or `query`, leaving two of three parameters undocumented anywhere.

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 (recent jobs) and a scope (newest first), plus a filtering mode, so an agent can tell it is a list/board view rather than a single-record fetch. It does not name any sibling (transcript_get, transcript_search, transcript_status) to sharpen the distinction, so it stops short of 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?

Usage is implied by 'for a board-level view of what is in flight, what is stuck and what is finished,' which suggests the monitoring/list use case. There is no explicit when-to-use versus transcript_search or transcript_status, and no statement of when not to use it.

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, the description carries the full burden and does well: it discloses the non-destructive, no-download behavior, that caption existence 'would make it near-instant' (a latency hint), and that it reports whether cookies are needed. It omits auth/permission requirements and rate-limit behavior, which keeps it from a 5.

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 defining constraint, and every sentence adds information. The final clause ('what would happen rather than what might') is slightly ornamental, and the line-broken formatting is a bit loose, but nothing is wasted.

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?

An output schema exists so return values need not be explained, and the description still previews the key signals an agent needs (duration, captions, cookies, existing). For a 3-param probe tool this is nearly complete; only auth/permission context and the captions default are unaddressed.

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 0%, so the description must compensate, and it does for the two meaningful params: it explains that captions/language drive the 'existing' check and must match create's values. The 'source' param is only implicitly described ('inspect a source'), and the default caption mode 'manual_only' is never explained, leaving a small gap.

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

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

States a specific verb and resource ('inspect a source') and immediately bounds the behavior ('without transcribing it, and without downloading it'), which separates it cleanly from transcript_create. The enumeration of what it reports (duration, caption presence, cookie need, existing transcript) makes the tool's effect unambiguous.

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

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

Strong contextual guidance: 'Pass the same language and captions you would pass to transcript_create' tells the agent this is a pre-flight check that mirrors create's settings. It does not explicitly state when not to use it or name sibling alternatives, so it falls just short of the top score.

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, the description carries the full behavioral burden and does disclosing meaningful traits: it works on a running job and only searches previously committed content, and it falls back to fuzzy matching when exact words fail. It does not state read-only/safety posture or rate/limit behavior, but the read nature is strongly implied by 'find'.

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 core action in the first sentence, then behavior and rationale in short paragraphs. Every sentence adds information; nothing is 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?

Output schema exists, so return values need not be described. The description covers purpose, use context, and runtime behavior (running jobs, fuzzy fallback), leaving only the underdocumented optional parameters as a 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 0% for all four parameters, so the description must compensate and largely does not. It hints at query semantics ('phrase') and timestamps (mapping loosely to context_seconds), but says nothing about max_results or how context_seconds bounds the returned window.

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 ('find a phrase in a transcript') plus a key output trait (timestamps). It names transcript_segments as a companion but does not distinguish itself from other search-adjacent siblings such as transcript_find_clips or transcript_get.

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 clear context for use: it is 'the intended way into a long transcript' alongside transcript_segments, with the rationale that pulling the whole transcript would flood context. It names an alternative but offers no explicit when-not-to-use or exclusions (e.g., versus transcript_find_clips).

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, the description carries the full burden and does disclose two non-obvious behaviors: overlapping (not just contained) segments are returned, and include_words roughly triples the response size so it defaults off. It omits prerequisites (e.g., whether the job must be finished), auth needs, and error 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?

Three short sentences, front-loaded with the core purpose, and each adds information. The straddling-boundary clause is slightly redundant with the preceding overlap sentence but usefully makes the rule concrete.

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?

An output schema exists, so return structure need not be described. The description covers the window semantics and the one costly parameter; only job prerequisites and time-unit details are missing, which is a modest gap for this complexity level.

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 0% across 4 parameters, so the description must compensate. It explains include_words' cost and default, and the overlap rule clarifies start_s/end_s window semantics, but job_id and the units/format of the time bounds are left entirely to the bare 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 with scope: 'Pull a time window of the transcript.' The boundary/overlap semantics further pin down exactly what is returned, which implicitly distinguishes it from transcript_get and transcript_search, though no sibling is named.

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 boundary discussion (use this when you want a slice rather than the whole transcript), but there is no explicit when-to-use or when-to-prefer-an-alternative guidance relative to transcript_get, transcript_search, or transcript_export.

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, the description carries the full burden and does so well: it enumerates the status lifecycle, explains that ``resumable`` is the authoritative retry signal, notes that ``download_urls``/``view_url`` only appear after output exists, and discloses that the links are loopback URLs served by this process. It even prescribes output presentation (markdown link in a sentence, not a code block), which is behavior an agent could not infer elsewhere.

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 core answer and organized into short, scannable paragraphs. The closing presentation advice is useful but runs long and repeats the same idea twice ("one link beats five" plus "Prefer offering view_url alone"), which is minor 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?

For a read-only status endpoint with an output schema present, the description supplies everything an agent needs beyond the schema: the status vocabulary, the retry signal, and the conditional presence and handling of result links. The only omission, job_id provenance, is minor for a polling tool.

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

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

The single required parameter ``job_id`` has 0% schema description coverage and is never mentioned in the description — no format, no indication of where to obtain it (presumably from transcript_create). With one undocumented required parameter, the description leaves a real gap rather than compensating.

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?

"Where a job stands: status, stage, progress, elapsed and ETA" gives a specific resource (an async job) and the exact facets returned, which is plainly distinct from siblings like transcript_get (content) or transcript_list (enumeration). An agent can tell this is the polling/status tool without opening any 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 actionable use-time guidance: use ``resumable`` rather than parsing error text, and surface download/view links once the job has produced output. It does not explicitly name an alternative tool or state when *not* to call it (e.g. how often to poll, or to use transcript_get instead once done), so it stops short of full routing guidance.

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