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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results come back newest-first — but says nothing about pagination, how 'latest' is bounded, or what happens on a bad channel identifier.

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 with zero filler, and the core operation is front-loaded before the ordering caveat. Nothing in the text is redundant with the name or 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?

For a simple three-parameter read tool with full schema coverage and strong annotations, this is nearly adequate, but there is no output schema and the description doesn't describe what a returned video record contains. The unresolved overlap with 'list_channel_videos' is the main completeness 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%, with all three parameters (channel, limit, timeout_seconds) fully documented including ranges and defaults. The description adds no parameter meaning beyond the schema, which is acceptable but sets the baseline at 3 rather than higher.

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: fetching the latest videos from a single YouTube channel, with an ordering guarantee ('newest first'). The purpose is clear in isolation, but the description never distinguishes it from the very similar sibling 'list_channel_videos' or 'search_channel_videos', leaving an agent unsure which to pick.

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 or when-not guidance, and no mention of the near-identical siblings 'list_channel_videos' or 'search_channel_videos'. The only usage-adjacent sentence is a data-ordering note ('videos tab is newest first'), which describes output shape rather than tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered structurally. The description adds value by enumerating the response facets (status, stage, error, billing), but says nothing about behavior on an unknown/expired job ID or whether billing data requires extra permissions.

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 front-loaded sentence with no filler; every clause (subject, returned fields, lookup key) carries information.

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

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

A read-only, single-parameter lookup with full schema coverage needs little more, and naming the returned fields compensates for the absence of an output schema. Only the not-found/error behavior is left 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 description coverage is 100% and the single job_id parameter already documents its UUID format and that it comes from transcribe or list_jobs. The description's "by ID" adds no 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?

Specific verb ("look up") plus resource ("TranscriptDock job") and the exact fields returned (status, stage, error, billing) scoped by ID. It is clearly distinct from list_jobs because it is ID-keyed rather than enumerating, but the description never names a sibling to reinforce that contrast.

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 "by ID" hints that an ID is required, but there is no explicit when-to-use guidance and no mention of the obvious alternatives in the sibling set (wait_for_job for blocking on completion, list_jobs for discovery). An agent must infer the polling-vs-blocking choice on its own.

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 readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds the useful precondition that only completed transcripts are fetchable, but the format/response-shape details are duplicated from the schema and there is no mention of what happens if the transcript is not yet ready.

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 front-loaded sentence with no filler; the resource, identifier, and possible output shapes all appear immediately.

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

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

For a two-parameter read tool with full schema coverage, an output-shape hint, and complete annotations, the description is nearly sufficient. The main omission is behavior on a non-completed or unknown transcript ID, which an agent would want to know before calling.

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 format enum already documents that segments is the default and text/srt/vtt return export bodies. The description merely restates those format options without adding semantics beyond the schema, so 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?

Names a specific verb (Fetch) and resource (completed transcript) plus the ID key, so the agent knows exactly what it retrieves. It does not distinguish itself from the sibling get_video_transcript, leaving ambiguity about which transcript tool to pick.

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 word 'completed' implies this only works after a job has succeeded, and listing formats hints at the export use case. There are no explicit when-to-use/when-not rules and no reference to alternatives like get_video_transcript or wait_for_job for pending 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). Beyond that, the description discloses the response shape — status, videos, cursor, error — which is genuinely useful because no output schema exists, and the presence of a cursor hints at pagination semantics worth knowing.

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 sentence, front-loaded with the verb and resource, with the return payload appended. Nothing is wasted, though the return-field list is a slightly breathless clause rather than structured.

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

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

For a single-parameter read with full schema coverage and full annotation coverage, the description covers purpose and return contents adequately. It lacks only guidance on failure modes (what happens when the ID is unknown) and on how the cursor field should be consumed, which are minor 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?

There is a single parameter and the schema already documents it at 100% coverage, including format, pattern, and the note that it is "returned by a listing tool." The description adds no syntax, format, or error-case detail about the id, 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 verb and resource ("Get one video discovery by ID") plus the payload it returns, so an agent knows exactly what this does. It does not need to differentiate strongly from the listed siblings (list_*, search_*, get_job), which are clearly distinct operations, though it never explicitly contrasts with a hypothetical list-video-discoveries tool.

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

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

Usage is only implied: "by ID" plus the schema note that the ID comes from a listing tool tells the agent this is a single-record fetch after a listing call. There is no explicit when-to-use/when-not statement and no named alternative for bulk retrieval.

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 substantial behavior beyond annotations: it discloses the long-polling/blocking nature, per-mode credit costs (1 credit captions_only, 2 credits/started minute for auto), and cache behavior that avoids re-charging. These are exactly the cost and latency traits an agent must know before invoking, and none are in the 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?

Front-loads the core action and mechanism, then layers usage and cost hints in a small number of dense sentences. Slightly packed, but every clause (polling, formats, credits, cache) carries information an agent needs.

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 still tells the agent what comes back (transcript text or srt/vtt/segments) and what happens on timeout (job state returned). Combined with documented cost/latency behavior, an agent has everything needed to call 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 coverage is 100% with enum descriptions and defaults already documented, so the baseline is 3. The description reinforces mode costs and the output format options (text/srt/vtt/segments) but adds little syntax or semantics not already in the schema.

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

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

States a specific verb+resource (get the transcript of a YouTube or TikTok video) and even explains the internal two-phase mechanism (submit job, long-poll, return text). It implicitly separates itself from get_job/wait_for_job by saying 'in one step', but never names the siblings get_transcript or transcribe, which an agent would need to disambiguate.

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-to-use guidance ('what does this video say' questions) and a concrete selection rule for the mode parameter (default captions_only, auto to fall back when no captions). No explicit when-not or named-alternative routing, 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.

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the pagination contract (cursor pass-through) which is genuinely useful beyond the annotations, but says nothing about ordering, rate limits, or the shape of the returned listing.

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 purpose and followed by the one operational rule that matters. No filler and nothing buried.

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 should characterize what 'the listing' contains (video IDs, titles, ordering, page metadata), but it only says it returns 'the listing'. Parameters and annotations are otherwise sufficient for correct invocation.

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

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

Schema description coverage is 100%, so limits, cursor opacity, channel formats, and timeout defaults are already documented, warranting the baseline 3. The cursor sentence echoes the schema's 'Opaque cursor from a previous call' rather than adding new semantics.

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 ('List videos from one YouTube channel') with clear scope, so an agent knows it retrieves a channel's video listing. It never names or distinguishes itself from close siblings such as get_channel_latest_videos or search_channel_videos, so the boundary is left implicit.

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 sentence 'Pass cursor unchanged for the next page' gives concrete pagination usage, but there is no guidance on when to choose this over get_channel_latest_videos or search_channel_videos, nor any stated prerequisites or exclusions. Usage is implied by the scope wording only.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond that: results are newest first and paginated with cursors.

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

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

The description is a single front-loaded sentence with no filler. Every element - resource, scope, ordering, and pagination - 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 simple read-only list operation with complete parameter descriptions and annotations, the definition is nearly complete. It could be slightly stronger by clarifying how workspace scope is determined, but nothing critical prevents correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents limit and cursor. The description reinforces cursor pagination but does not add format or usage details beyond what the schema provides, making the baseline score 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 verb and resource: it lists jobs for the workspace. It also adds scope details (newest first, cursor pagination), but it does not explicitly distinguish this from siblings such as get_job or wait_for_job.

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 listing purpose and pagination model imply this is for enumerating jobs rather than retrieving one job or waiting on a job. However, it does not explicitly say when to use this tool instead of get_job or wait_for_job, nor does it state exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that by disclosing pagination semantics and the constraint that the cursor must be passed back unchanged. Missing auth/quota notes keep 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?

Two short sentences with no filler; the core action is front-loaded and the pagination rule follows immediately. Every sentence carries information the agent needs.

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, and 'return the listing' gives only a vague sense of the response shape, which is the main gap. Given rich annotations and full schema coverage, the definition covers everything else needed to call 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 four parameters are documented in the schema itself, making 3 the baseline. The description reinforces the cursor contract ('unchanged') but adds nothing about playlist identifier format, limit behavior, or timeout.

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 and resource ('List videos from one YouTube playlist'), and the scope qualifier 'one YouTube playlist' separates it from channel-level siblings like list_channel_videos and search_channel_videos. It stops short of naming an alternative explicitly, so it is clear but not maximally differentiating.

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 only usage instruction is pagination-related ('Pass cursor unchanged for the next page'), which is genuinely useful but narrowly scoped. There is no statement of when to choose this over search_channel_videos or list_channel_videos, so the choice between siblings is left to inference.

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?

Goes well beyond the read-only/idempotent annotations by disclosing a hard upstream limitation: at most 10 videos from the embed page with no further pagination. It also flags that include_details causes an additional fetch per video, which carries cost/latency implications. Missing only notes on failure modes or auth.

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, each earning its place: purpose first, then the hard cap, then the option tradeoff. No restatement of the tool name or 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 simple read-only list tool with full schema coverage, the description covers the essential surprises (10-video ceiling, per-video fetch cost). Without an output schema, it could say a word about what each result contains (IDs, URLs, basic stats), but nothing critical 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, but the description adds real meaning: it explains that include_details performs one extra fetch per video and caps the effective result count at 10, which the schema only states tersely. The user and timeout parameters are left entirely to 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 ('List TikTok videos for one user'), and the platform qualifier alone separates it from YouTube-oriented siblings like list_channel_videos and search_youtube. An agent can route correctly 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 rules out a tempting alternative ('TikTok search is not available') and tells the agent when to set include_details ('to also fetch each video page'). It does not name a sibling tool to use for other platforms, but the usage context is otherwise clear.

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, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the cursor pass-through rule for paging; it says nothing about result shape, empty-result behavior, or quota/rate implications of openWorld access.

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 filler, the core action front-loaded and the pagination rule following it. 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 is the only place to learn what the 'listing' contains, and it does not say. Combined with the absence of sibling differentiation against list_channel_videos, an agent has enough to invoke it but not enough to choose it confidently.

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 every parameter (limit, query, cursor, channel, timeout_seconds) is already documented, setting the baseline at 3. The description's note about passing the cursor unchanged for the next page slightly enriches cursor semantics but adds nothing for channel format or query matching behavior.

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 clear scope: 'Search videos within one YouTube channel and return the listing.' The channel-scoped search is distinguishable from a generic search, though the description never names the obvious sibling list_channel_videos, so an agent must infer the search-vs-list distinction.

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 only usage guidance is pagination: 'Pass cursor unchanged for the next page.' There is no statement of when to pick this over search_youtube (site-wide) or list_channel_videos (unfiltered listing), which is the primary selection decision for this family of tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the paginated listing behavior and the rule that the cursor must be passed back unmodified — a behavioral detail no annotation encodes.

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, with the core action front-loaded and the pagination hint second. Every clause carries information an agent needs.

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 search tool with full schema coverage and no output schema, the definition covers action, pagination and safety adequately. The remaining gap is that "return the listing" does not say what a listing item looks like, and no output schema exists to compensate.

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 query, limit, cursor and timeout_seconds are all documented in the schema, which sets the baseline at 3. The description only reinforces cursor semantics ("pass unchanged"), adding little beyond "Opaque cursor from a previous call" and saying nothing about limit or timeout behavior.

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 ("Search YouTube videos by query") plus the return shape ("return the listing"), which clearly separates it from siblings like get_video_transcript or list_playlist_videos. It never contrasts itself with the closest sibling, search_channel_videos, so the global-vs-channel scope must be inferred.

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 second sentence gives real procedural guidance for paginating ("Pass cursor unchanged for the next page"), which is the main usage pitfall. However, there is no statement of when to prefer this tool over search_channel_videos or get_video_discovery, so the routing decision is left implicit.

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 cover safety (readOnlyHint false, idempotentHint true, openWorldHint true) and the schema covers the max_credits budget failure. The description adds genuinely new behavioral context: per-mode credit costs and the 'paid plans' restriction on AI transcription, which an agent needs to avoid surprising charges.

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 waste: the action and return value come first, then the cost/mode decision information that actually affects the call. Each 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 5-parameter create-job tool with full schema coverage and annotations, the description covers action, return value, and cost tradeoffs. It doesn't describe the returned job object, but with no output schema a brief pointer to get_job would have closed the last 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% and every parameter is documented, so the schema does the heavy lifting and the baseline is 3. The description's mode cost explanation largely restates the mode parameter's own description, adding no syntax or format detail the schema lacks.

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 ('Submit'), specific resources (YouTube or TikTok URL), the service (TranscriptDock), and the outcome ('return the created job'). That outcome clause distinguishes it from get_job, which retrieves an existing job.

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 mode/cost breakdown gives clear guidance for choosing captions_only vs auto vs transcribe, including when auto falls back to AI. It doesn't explicitly exclude this tool in favor of siblings like get_video_transcript for already-submitted URLs, but the create-job framing implies 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 already cover readOnly/idempotent/non-destructive, and the description adds the genuinely useful behavioral fact that this is a blocking long-poll call that returns only on terminal status. It omits what happens on timeout (only stated in the schema) and any note about connection duration or rate limits.

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 sentence, front-loaded with the blocking purpose and ending with the terminal-state enumeration. Every clause carries information; 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?

For a two-parameter blocking read with full schema coverage and safety annotations, the description is nearly complete. The one gap is that with no output schema, it says only 'return it' without indicating the shape of the returned job object or the timeout-state payload.

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

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

Schema description coverage is 100%, with both job_id and timeout_seconds fully documented including the 300 default and 1800 max. The description adds no parameter-level meaning beyond that, 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 ('wait'), a specific resource (a job), and enumerates the terminal statuses it resolves on, so its blocking semantics are distinguishable from get_job's immediate read. It stops short of naming get_job or list_jobs explicitly as the non-blocking 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?

Usage is only implied: an agent can infer 'use this when you need to block until completion,' but the description never says when to prefer this over get_job polling or list_jobs. No exclusions, prerequisites, or alternatives are stated.

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