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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds genuinely new behavioral context: there is no storage quota, the library is bounded by time via `retention`, and `library.completedTranscriptions` is a bounded count where `isCapped=true` means the real value is higher than reported. That last point is important data-accuracy disclosure an agent could not 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?

Front-loads what the tool returns, then adds two short clarifying notes about cost and library capping. Four sentences with no filler, though the backticked field references (`retention`, `library.completedTranscriptions`, `library.isCapped`) get dense for a short description.

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 return-value burden, and it covers the main items (balance, tier, library counts, retention) plus the `isCapped` caveat. It does not sketch the full response shape or the format of the retention value, which is a minor gap for a simple no-arg read 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 tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. The description correctly does not waste space on non-existent inputs.

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 (check) and enumerates the exact resources returned: credit balance, subscription tier, stored completed transcriptions, and retention duration. It is clearly distinguishable from the transcription-oriented siblings (transcribe_video, list_transcriptions, etc.) since no other tool exposes account/billing state.

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: mentioning 'Each transcription costs 1 credit' suggests calling this as a pre-flight affordability check. It never states when to prefer this over siblings or any condition where it should not be called, so guidance is implied rather than 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?

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds genuinely non-redundant behavioral detail: the response shape varies by state (full text plus extracted comments when completed, status/error otherwise), which is important for an agent deciding whether to retry or poll. It does not note whether a lookup by a nonexistent ID errors or returns null.

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. The retrieval contract is front-loaded and the state-dependent return behavior follows immediately; every clause earns its place.

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

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

With no output schema, the description correctly carries the burden of explaining return values across states, and annotations cover the safety profile. The one real gap is that both parameters are optional (required: 0) yet the description never says what happens if neither is provided, nor whether it polls or fails while processing.

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 both parameters are already documented as 'Transcription ID' and 'Transcription job request ID'. The description only restates that lookup is possible by either key, adding no syntax or precedence detail (e.g., which wins if both are supplied). Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource (retrieve a transcription) and specifies the two lookup keys, which cleanly separates it from list_transcriptions and search_transcriptions. It stops short of naming a sibling explicitly or describing the broader transcribe workflow, so it earns a solid 4 rather than 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: call this after a transcription exists, using either the transcription ID or the job request ID. There is no explicit when-to-use/when-not guidance, no mention of alternatives such as list_transcriptions for discovering IDs, and no guidance on polling when the job is still processing.

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, non-destructive and openWorld, so the safety profile is covered by structured data. The description adds two real behavioral facts — results are paginated one page at a time and are scoped to the connected account — but says nothing about ordering, cursor lifetime, or whether listing includes completed/failed jobs.

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

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

Two short sentences, front-loaded with the core action and the mode distinction, with no filler. The trailing sentence about account scope is brief and purposeful, though slightly vague.

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 and 0% schema description coverage, the definition should describe what a returned job record contains (status, type, timing) and how cursor pages terminate. It covers the action and scope but leaves the return payload opaque.

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 carry parameter meaning. It implies bulkJobId selects a progress read, but never names 'cursor' or explains that it advances pagination, leaving one of two parameters unexplained 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?

The description gives a specific verb ('List') plus resource ('batch/channel jobs') and distinguishes two modes: paging through jobs vs. reading progress for a specific bulkJobId. It is clear what the tool does, though it does not name any sibling by 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?

Usage is only implied: the presence of bulkJobId suggests a targeted progress read, while omitting it implies listing a page. There is no explicit 'use this when... use X instead' guidance and no mention of how it relates to siblings such as transcribe_bulk or get_transcription.

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 establish readOnly/idempotent/non-destructive, so the bar is lower; the description adds non-obvious behavior: no library total is reported, libraryTotal is populated only for a complete first-page result, and results come back as previews. These are genuine behavioral disclosures 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 dense sentences, all front-loaded with the most important constraint (ONE PAGE, newest first) first. Every sentence carries distinct information about pagination or return shape; 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?

With no output schema, the description helpfully characterizes the return payload (hasMore, nextCursor, libraryTotal, previews), which an agent needs to paginate correctly. It is nearly complete; only a few filter params (platform, bulkJobId, date range) go unexplained across both schema and description.

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

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

Schema coverage is 67%, so the schema documents most params. The description clarifies cursor's relationship to nextCursor and restates the limit default/max, but leaves owner, platform, bulkJobId, requestIdFilter and endDate to the schema (several of which have no schema description at all). It adds value on cursor but doesn't fully compensate for the uncovered params.

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 ('list your transcriptions') with a clear scope modifier (ONE PAGE, newest first). It does not, however, name or distinguish itself from sibling list/search tools like search_transcriptions, so an agent must infer the boundary rather than being told 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?

The description explains the pagination flow well ('cursor selects a subsequent page', 'hasMore/nextCursor describe pagination'), which implies how to iterate. But it gives no explicit when-to-use guidance versus search_transcriptions or get_transcription, and no when-not-to-use 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: the search is scoped to a bounded window of recent transcriptions, results are capped, and thus `found: false` does not prove absence while `matchesReturned` is not a library-wide count. This directly prevents agent misinterpretation of results.

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 what the tool does, then the result shape, then the caveats, with no filler. The final clause is a dense run-on packing two distinct caveats, but both earn their place for a tool whose failure mode is a misleading empty result.

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 return contract itself: newest match returned in full plus ids of other matches, with explicit meaning for `found` and `matchesReturned`. Combined with annotations and a fully documented single param, nothing needed to call or interpret the tool 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?

With one parameter at 100% schema coverage, the baseline is 3; however the description adds real semantics beyond the schema by specifying that matching is substring containment against the *original* video URL, not exact equality. That clarifies how to formulate the input value.

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

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

States a specific verb (find/search) plus resource (transcriptions) and the exact matching rule (original video URL contains the given string). It is clearly distinguishable from get_transcription (fetch a known one), list_transcriptions (enumerate), and transcribe_video (create one).

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 explicit usage context: 'Useful for checking whether a video has already been transcribed.' It even clarifies the semantics of a negative result, which is a usage-level caveat. It stops short of naming a sibling alternative or stating when-not-to-use, so it is strong but not 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 declare the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true) but say nothing about cost or consent. The description supplies the missing operational context: 1 credit per new video, tier-dependent batch ceiling, reuse of existing transcripts, and the API-key/consent gate. It does not explain what 'destructive' means here (credit consumption, job side effects) or how to track the returned job.

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?

Five short sentences, all carrying distinct information (limit, cost, reuse, return value, auth), with the core action front-loaded. Dense and waste-free, though slightly staccato and fragmentary.

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?

No output schema exists, so the description correctly states the return value ('a bulk job ID'). Combined with cost, reuse, tier limits, and the auth gate, an agent has what it needs to invoke correctly; only polling/status follow-up is unaddressed, and list_jobs sibling likely covers that.

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

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

One parameter with 0% schema description coverage, so the description must compensate. It confirms the 1,000-URL ceiling (matching maxItems) and adds the credit cost per URL, but says nothing about URL validity constraints or what happens on partial failure within the array.

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 ('Submit ... video URLs as a batch') and the scale (up to 1,000), which signals it is the plural counterpart to transcribe_video without naming it. Clear enough to route correctly, but the sibling differentiation is implied by 'batch' rather than stated.

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

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

The word 'batch' implies when to use this over transcribe_video, and it names a prerequisite ('Requires an API key or additional batch transcription consent'), but it never states the condition for choosing bulk over single submission or when this tool should not be used.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false and non-idempotency, and the description adds real behavioral context: 1 credit reserved per requested reel, refund rules, paid-plan gating, and the consent/API-key requirement. It still omits what happens on partial failure or how credits are refunded in edge cases, but it goes meaningfully beyond 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?

Four short sentences, front-loaded with the action and resource, with eligibility and cost details following. Every sentence carries distinct information; only the refund-rules clause is slightly opaque without further detail.

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 credit-consuming, non-idempotent batch tool with no output schema, the description covers limits, cost, eligibility, and consent requirements, which is most of what an agent needs before invoking. Return shape and pagination behavior are absent, but no output schema exists to lean on.

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 carry the load. It does convey the reelCount cap ('up to 50 reels') and the optional date filter ('optionally after a date'), but it adds no format, pattern, or username-syntax detail for channelUsername or onlyPostsNewerThan. It partially compensates but leaves gaps.

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 ('Transcribe ... reels from an Instagram channel') with a hard scope limit of 50. It is clearly distinguishable from get/list/search siblings by resource, though it does not explicitly contrast with the closely related transcribe_bulk or transcribe_video.

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 useful eligibility conditions ('Paid plans only', 'Requires an API key or additional batch transcription consent') and the optional date scoping. However, it never states when to choose this over transcribe_bulk or transcribe_video, so the routing decision 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?

Annotations declare openWorldHint, idempotentHint and destructiveHint, but the description adds genuinely new operational context: 1 credit per new job, free reuse of matching existing transcripts, and no storage quota. It does not explain what the destructiveHint implies (e.g. credit consumption or job side effects), leaving that annotation unexplained.

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, front-loaded sentences that each carry information: purpose first, then supported platforms, then the two cost rules. Slightly compressed and no wasted clauses, though the cost/reuse lines sit after the platform list rather than being grouped.

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

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

For a tool that creates jobs, consumes credits and has no output schema, the description covers cost and reuse well but never says what is returned, how long the blocking wait may take, or how to fetch a transcript later. Those gaps are meaningful given the absence of an output schema, though existing transcripts being reused is well communicated.

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

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

Schema description coverage is 100%, so both parameters (url and includeComments) are already fully documented in the schema. The description adds no extra parameter semantics, which is the expected baseline of 3 when the schema carries the load.

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 ('Submit a video URL for transcription and wait for the result') and enumerates the supported platforms (Instagram, TikTok, YouTube, Facebook), which concisely delimits scope. It does not name any sibling, so the split from get_transcription or transcribe_bulk must be inferred from the submit-vs-retrieve wording.

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: an agent can infer it should call this to obtain a transcript for a single video URL. There is no explicit when-to-use / when-not-to-use guidance and no pointer to alternatives like get_transcription for retrieval or transcribe_bulk for multiple 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds value beyond that by stating it has no transcription side effect and by disclosing the return shape (detected platform + normalized URL), which annotations do not convey.

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, front-loaded with the validation purpose followed by the return values. 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?

No output schema exists, so the description must summarize the response, and it does so explicitly (detected platform and normalized URL). Combined with the annotation-provided safety profile, 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents 'url'. The description adds nothing about format or accepted URL variants, so the baseline 3 applies.

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

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

States a specific verb (check/validate) applied to a specific resource (URL) and enumerates the supported platforms. It also distinguishes itself from the sibling transcribe_video by clarifying it does not submit for transcription.

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 'without submitting for transcription' clearly frames when to use this tool (pre-flight support check) rather than triggering a job. No explicit named alternative or when-not condition is given, but the context for use is unambiguous.

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