LLMExpert transcription

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), it discloses that ingestion runs in the background (async), that two source types fail with 501 until released, and that a write-scoped key is required. These are exactly the behavioral traits an agent needs before calling a mutating 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 sentences: action, endpoint mapping, then constraints. Constraints are front-loaded rather than buried, and no sentence 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?

For an async mutation with no output schema and fully documented params, the description covers action, auth, and failure modes. It omits what success returns (e.g. an ingestion/job handle) and how it relates to add_sources, which an agent choosing between the two would want.

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 genuine value about the `type` discriminator by explaining the runtime status of each value (video supported, document/website reserved with 501). channel_id and idempotency_key semantics are left 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+resource ('Add a source to a channel') and even names the underlying endpoint, so the operation is unambiguous. It does not differentiate from the sibling add_sources, leaving the singular/plural distinction to 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?

Gives real usage conditions: only type: video works today, document/website return 501, and the key needs write scope. It stops short of routing to alternatives such as add_sources for batch adds or get_status for polling ingestion.

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

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

Annotations only cover readOnlyHint=false and openWorldHint=true; the description carries the rest: per-minute pricing tiers, a 1-minute per-video minimum, the free case for duplicates, the write-scope API-key requirement, and the asynchronous job lifecycle with its terminal statuses. This is far more behavioral context than the annotations supply.

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?

Dense and mostly front-loaded, with the action stated first, but it opens with a fragment ('Charged like `transcribe`.') and repeats the pricing point twice ('$0.10/min ... by default' and 'Prices are the service defaults'). Eight sentences for one tool is on the heavy side, though nearly all carry real 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?

With no output schema, the description still supplies what an agent needs to interpret results: the status vocabulary, the meaning of `completed` (transcribed and indexed, collection queryable), and the polling cadence. Auth, pricing, idempotency, and dedup behavior are all covered, so nothing material 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 pricing meaning to parameters the schema only labels: quality drives $0.10/min vs $0.25/min, and quote_id locks an exact quoted price. It leaves max_videos_per_channel and the channel_url/url split 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 ('start an ingest job in an existing collection' for the given YouTube URLs), names the exact endpoint POST /v1/collections/{collectionId}/sources, and uses 'Expand' to signal that channels/playlists are flattened into individual videos. An agent knows precisely what happens as a result of calling 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?

Gives concrete operational guidance: pass a quote_id from `quote` to lock the price, poll `get_status` every 10-30s until completed/partial/failed, and notes that videos already in the collection are free. It references two siblings (quote, transcribe) but never explicitly routes the agent between this tool and its near-identical sibling add_source (singular), which is the most likely selection mistake.

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 annotations (readOnlyHint=false, openWorldHint=true) by disclosing cost ('Free'), auth requirements (API key with write scope), the underlying POST endpoint, and critically that the `collection_token` is shown once and absent on an idempotent replay. It also clarifies that prices are service defaults and `quote` gives exact pricing.

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?

Dense and front-loaded, with the key operational facts (cost, purpose, auth, token handling) stated up front. It packs several distinct facts into a few sentences, which borders on terse, but 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?

With no output schema, the description carries the return-value burden itself and does so: it names the returned collection and the one-time `collection_token`. Auth, cost, idempotency behavior, and follow-up workflow are all covered, so an agent has everything needed to call and handle the response.

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, which sets a baseline of 3. The description adds meaning the schema lacks: the idempotency key's observable effect (token absent on replay) and that pricing isn't specified per-call. It doesn't explain the title parameter, but the schema fully covers it.

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

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

States a specific verb and resource ('Create an empty collection') and immediately distinguishes it from the sibling that populates it ('add sources to later with `add_sources`'). An agent can tell this apart from add_source/add_sources without opening a schema.

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

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

Explicitly positions the tool in a workflow: create the empty collection first, then add sources with `add_sources`. It does not state when NOT to use it (e.g. versus quote or query_collection), but the sequencing guidance is clear enough for correct 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=true and openWorldHint=true, so safety is covered; the description goes beyond them by disclosing the required `read` scope (auth prerequisite) and the backend endpoint, which helps an agent predict failures rather than behavior of the call itself.

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

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

Two sentences, zero filler, with the core action and return shape front-loaded and the auth requirement appended as a practical footnote.

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 compensates by naming what comes back (source plus processing status with type-specific provenance), and it flags the auth scope. It stops short of describing error/404 behavior or the format of the provenance data, but nothing essential for correct invocation is missing.

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

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

Only one parameter exists and schema description coverage is 100% with an example value ('src_71b0e4.'), so the schema already does the work; the description adds no additional meaning about the identifier format or constraints. Baseline 3 for a fully documented single-param 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 ('Fetch a single source') plus the returned payload ('processing status', 'type-specific provenance'), which is enough to separate it from list_sources, get_status and get_transcript without opening a schema.

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

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

The scope ('a single source', identified by sourceId) implies the usage context, but there is no explicit when-to-use guidance or routing to alternatives such as list_sources or get_status for aggregate/batch needs. The API mapping hint adds orientation but not selection criteria.

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

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

Annotations only supply readOnlyHint and openWorldHint, and the description adds substantial context beyond that: auth options (API key or the collection's `ct_` token as bearer), what `completed` vs `partial` mean operationally, and that failed videos are credited back via `credited_usd`. It also clarifies that prices are service defaults and `quote` gives exact pricing.

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 purpose and lifecycle semantics before the trailing pricing note. Dense but nearly every sentence carries operational value; the final pricing/`quote` remark is slightly tangential to a status poll.

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 carries the burden of explaining returns, and it does: `status` values and their meanings, `credited_usd`, and `videos.completed` / `videos.failed` progress counters. Combined with auth guidance, an agent can call and interpret this 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?

There is a single parameter with 100% schema description coverage, so the schema already documents `job_id`. The description's 'from `transcribe` or `add_sources`' wording mirrors the schema text and adds no format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get an ingest job') plus the origin of the identifier ('started by `transcribe` or `add_sources`') and the underlying endpoint. This distinguishes it cleanly from sibling `get_source` / `get_transcript` and from the creation tools it pairs with.

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 operating procedure: poll every 10–30 s until `status` is completed, partial, or failed. It also defines which states are terminal, which is exactly the when-to-use / when-to-stop guidance an agent needs for a polling endpoint.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description goes further: it discloses the 404 conditions (video not completed in the collection, or transcript predates the cache), auth/token behavior, cost default behavior, and the effective endpoint. This is rich, non-redundant behavioral context.

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?

Dense but each sentence carries distinct information (cost, endpoint, auth, format, error, pricing). The leading 'Free.' is punchy and front-loads the key differentiator, though the later pricing sentence is slightly at odds with it.

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

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

For a 3-param read tool with no output schema, the description covers auth, format semantics, and failure modes. It could say a bit more about the returned payload structure, but nothing needed to invoke it correctly 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 baseline is 3, but the description adds real meaning: collection_id's requirement flips depending on API key vs `ct_` token, and format is spelled out (json = timestamped segments, text = one `[H:MM:SS] text` line per segment) beyond the schema's terse enum note.

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 video) and scopes it ('completed in one of your collections'). The endpoint mapping (GET /v1/videos/{youtubeId}/transcript) and the free/non-free framing against the sibling 'transcribe' make it distinguishable from siblings without opening schemas.

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 conditions: collection_id required with an API key but defaulted with a `ct_` token, and format selection. It also routes pricing questions to the sibling 'quote'. However it never directly contrasts with 'transcribe' (the tool that presumably produces the transcript), leaving that inference to the reader.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond the annotations by disclosing the auth requirement (`read` scope) and the fact that it is scoped strictly to the calling key. It does not mention rate limits or caching, 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?

Two compact sentences: the first front-loads what is returned, the second adds endpoint and auth constraints. Every clause carries information with no filler or repetition of the title.

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

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

With no output schema, the description helpfully enumerates the payload fields (queries, tokens, cost, budget remaining), which compensates for the missing return contract. Auth requirements and scope are covered. It stops just short of fully adequate because response shape, units, and pagination or time-window behavior remain unstated.

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 optional enum parameter (`period`, default `current`) is fully documented in the schema. The description adds nothing about the parameter's semantics, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (usage, quota, spend) plus the exact scope (the calling key), and enumerates the returned data (queries, tokens, cost, budget remaining). It even maps to GET /v1/usage, so an agent knows precisely what the call does and that it cannot target another key. Sibling tools (sources, channels, transcripts) are obviously unrelated, so no disambiguation is needed.

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 states a precondition ('Requires the key's `read` scope'), which is genuinely useful selection context. However, it gives no explicit when-to-use framing, no exclusions, and no alternatives to prefer. Usage is implied by the name rather than explained.

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 and openWorldHint, so the safety profile is covered. The description adds real context beyond that: results are scoped to the key's permissions, the call is cursor-paginated, and the read scope is required. It does not state the default/exact return shape, but no output schema exists to cover that either.

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: what it returns, the underlying endpoint, then pagination and auth. No filler, and the scoping constraint comes first where it matters most.

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, zero-required-parameter list tool with no output schema, the description covers scope, endpoint mapping, pagination, and auth requirement — enough to invoke correctly. Missing only an explicit statement of the default page size behavior, which the schema already carries.

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 limit and cursor are already documented in the schema. The description adds only the 'cursor-paginated' framing, which reinforces rather than extends the cursor parameter — 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 and resource ('List the channels') plus the scoping constraint that only channels the calling key can see are returned. It does not explicitly distinguish itself from the sibling list_sources, so the agent must infer the channel/source split from the resource noun alone.

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

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

Gives a prerequisite ('Requires the key's read scope') which is genuine usage guidance, but never says when to prefer this over list_sources or query_channel. Usage is implied by resource name rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, yet the description still adds real value: the API mapping (GET /v1/channels/{channelId}/sources), cursor-based pagination, and the required `read` scope. That auth and pagination context is not derivable from 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?

Three tight sentences, front-loaded with the core purpose followed by pagination and auth details. Every sentence earns its place with no filler.

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

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

For a 5-param read-only list tool with no output schema, the description covers purpose, filtering, endpoint, pagination, and scope requirement. It omits the shape of returned items, but the mention of cursors makes the call pattern clear enough.

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 type, status, limit, cursor, and channel_id are already documented. The description only restates that type/status are filters and that results are cursor-paginated, adding no syntax or semantic detail beyond the schema. 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 (list), resource (sources), and scope (in a channel), and even defines what a source is (video/document/website). It does not explicitly name a sibling such as get_source or query_channel, so it falls just short of full sibling differentiation.

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 scope and the optional type/status filters, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives like get_source for a single item or query_channel for content search. Adequate but leaves selection 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 readOnlyHint and openWorldHint, so the safety profile is covered; the description adds real behavioral context beyond that: required query scope, channel-access constraint, and that the result is a generated answer with citations rather than raw chunks. It doesn't cover rate limits or top_k behavior, but the additions are substantive.

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, with the core purpose front-loaded and the REST mapping and auth requirement following in priority order.

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

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

With no output schema, the description carries return-value burden and does so by stating a generated answer with citations. Combined with the documented auth scope and a fully-described parameter schema, it is nearly complete; only retrieval controls (top_k defaults, session behavior) and rate/limit expectations 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 description coverage is 100%, so every parameter is already documented in the schema, making 3 the baseline. The description adds no parameter-specific meaning (e.g., how session_id interacts with multi-turn or how source_types affects citations), so it does not exceed the baseline.

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+resource: 'Run a retrieval-augmented query against a channel's indexed knowledge base and return a generated answer with citations,' plus the REST mapping POST /v1/query. It clearly conveys what the tool does, but it never explicitly distinguishes itself from the sibling query_collection beyond the word 'channel.'

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?

States a prerequisite ('Requires the key's query scope and access to the channel'), which is useful context for when the call will succeed. However, it gives no guidance on when to choose this over query_collection, nor any when-not conditions.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds the full behavioral picture: $0.05 flat pricing, the x402 keyless payment handshake (payment-required result, retry with _meta, receipt in _meta), and the explicit rule to never re-pay after a 409 or 502. This is exactly the kind of cost/error/auth context annotations cannot carry.

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 cost is correctly front-loaded and the payment mechanics are compressed into dense but non-redundant sentences. It runs long for a single tool, but nearly every clause conveys an actionable constraint (scope, 409/502 handling, ownership), so little 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?

With no output schema, the description still tells the agent what comes back (answer with citations, payment-required result in structuredContent, receipt in _meta). Combined with the pricing, auth, and retry semantics, nothing needed to invoke this correctly 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 100%, so all four parameters are already documented in the schema, and the description adds no syntax or constraint detail for query, session_id, or idempotency_key. The _meta['x402/payment'] mention is a transport mechanism, not a tool parameter. 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+resource ('Ask a question of a collection and get a generated answer with citations') and pins it to an HTTP endpoint. The resource (collection) clearly separates it from the sibling query_channel without needing to open either 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 an explicit precondition ('Query a collection once get_status says completed'), names a sibling for pricing exactness ('quote returns the exact price'), and states the auth requirement ('needs the key's query scope'). It also specifies the keyless ownership rule, so the agent knows when this call is even permitted.

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 readOnly/openWorld annotations by disclosing that the call is free, that `quote_id` expires after 15 minutes, that the key must carry the `read` scope, and that the returned price is the exact charge if the id is reused. Rate/TTL/auth/cost traits are all surfaced.

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 most decision-relevant fact ('Free') and keeps sentences tight. Slightly diluted by the trailing 'Prices are the service defaults; `quote` returns the exact price,' which largely restates the earlier pricing sentence.

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, yet the description names the return shape (price, per-video lines, per-source rejections), the pricing basis, the id lifecycle, and the auth requirement. An agent has everything needed to call and interpret it without guessing.

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 constraints the schema does not encode: 'At least one of url, urls, channel_url, channel_urls' on a schema whose required list is empty, plus the rule that videos already in a supplied collection are free. It does not explain `max_videos_per_channel` defaults beyond what the schema already says.

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+output: 'Expand YouTube URLs exactly as an ingest would and return the price, the per-video lines and the per-source rejections.' The mapping to POST /v1/quote and the pricing semantics make it unmistakably distinct from transcribe (which actually charges) and query_channel/query_collection.

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 operating context: it's free, the `quote_id` is passed to `transcribe` or `add_sources` to lock in the price, and `collection_id` prices against an existing collection. It does not explicitly state when NOT to bother quoting (e.g., trivial single-video flows) or contrast against sibling pricing paths, 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.

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

Annotations only give readOnlyHint=false and openWorldHint=true, so the description carries the real burden and does: pricing tiers and minimums, required write scope, the $0.10/$0.25 per-minute model, the x402 keyless payment handshake including where the payment-required result and receipt appear, and the one-time collection_token disclosure. This is far beyond what annotations 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?

The lead sentence front-loads the action, the return fields and polling guidance are compact, and the payment paragraph is dense but each clause is operationally necessary. It is a long block of prose rather than scannable structure, which costs it a point.

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 10-parameter, zero-required, no-output-schema, payable mutation, the description covers creation, cost, auth, keyless limits, idempotency, return values and the polling completion contract. Nothing an agent needs to call this correctly and interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema does not: quote_id yields an exact quoted charge (400 if unknown/expired), keyless mode constrains input to one source and ≤3 videos, and quality defaults to whisper pricing. It does not document the url vs. urls vs. channel_url family split, which is the one real ambiguity left.

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 compound action — create a collection and start an ingest job for YouTube URLs — in one call, and names the HTTP mapping. The 'in one call' phrasing implicitly contrasts with the sibling pair create_collection + add_sources, so the agent can route without opening schemas.

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 quote to lock a price and pass quote_id, poll get_status every 10–30 s until terminal status, and never pay again after a 409 or 502. It also states the keyless precondition (one channel-like source, at most 3 videos) that selects an alternate usage mode.

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