Cited Q&A over 2026 conference talks and YouTube videos. $0.02/query, free daily tier, key or x402.
Scored across 14 tools
Most tools target distinct resources/actions, but the ingest trio add_source, add_sources, and transcribe overlaps around adding YouTube URLs, and query_channel, query_collection, and search_talks all return cited Q&A against different targets. The descriptions do clarify the distinctions, so confusion is limited but possible.
Names are consistently snake_case and mostly verb-first (add_source, get_status, list_sources, query_collection). Minor deviations are quote and transcribe without a noun, plus the singular/plural pair add_source/add_sources.
With 14 tools, the set is well-scoped for an ingestion-plus-Q&A service. Each tool covers a distinct part of the workflow: pricing, ingestion, status polling, listing, retrieval, querying, transcripts, and usage.
Core workflows are covered: quote, ingest, poll, query, transcript, and usage. However, collection lifecycle coverage is incomplete: there is create_collection but no list_collections, get_collection, or delete_collection, and there is no delete/update for sources.
Add a source to a channel and begin background ingestion. Maps to POST /v1/channels/{channelId}/sources. Only type: video is processed today; document and website are reserved and return a 501 error until released. Charged from the key owner's prepaid balance at the ingest rate: $0.01/min standard, $0.03/min whisper by default, 1-minute minimum per video. A short balance returns a 402 error. Requires the key's write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The source to add (discriminated on `type`). | |
| channel_id | Yes | Channel to add the source to. | |
| idempotency_key | No | Idempotency-Key for safe retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false and openWorldHint=true in annotations, the description carries real weight: async background ingestion, per-type 501 behavior, prepaid billing rates with a 1-minute minimum, 402 on short balance, and required `write` scope. That is exactly the cost/auth/failure context annotations cannot express.
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 tight sentences: action and endpoint first, then type support limits, then pricing/error behavior, then auth. No filler, and the highest-risk facts (cost, 501, 402) are front-loaded enough to be read before invoking.
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 mutating, externally-billed, no-output-schema tool, the definition covers cost, auth, async behavior, and error codes well. It is slightly incomplete on what the call actually returns (a source/ingestion handle?) and on how `idempotency_key` interacts with the background job, which matters for retries.
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 3 baseline applies to the parameter shapes themselves. The description still adds genuine meaning beyond the schema by declaring that two of the three `type` discriminators are non-functional today, which the schema presents as equally valid options.
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 (add) plus resource (source to a channel) and the side effect (begins background ingestion), and pins it to POST /v1/channels/{channelId}/sources. It does not distinguish itself from the sibling `add_sources` (plural), leaving an agent to guess which of the two to call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage constraints are stated as facts (only `type: video` is processed; `document`/`website` return 501), which effectively tells the agent what not to attempt. However there is no explicit routing guidance against the near-identical sibling `add_sources`, and no stated prerequisites beyond the `write` scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Charged like transcribe. Expand the given YouTube URLs, charge for the new work and start an ingest job in an existing collection. Maps to POST /v1/collections/{collectionId}/sources. $0.01/min standard, $0.03/min whisper by default, 1-minute minimum per video. Videos already in the collection are free. Pass a quote_id from quote to be charged exactly that price. Poll get_status every 10–30 s until status is completed, partial or failed; completed means every accepted video is transcribed and indexed, so the collection is queryable. API key required (the key's write scope). Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | One YouTube URL (video, @handle, /channel/UC…, or playlist). | |
| urls | No | Several YouTube URLs. | |
| quality | No | Transcription quality (default standard). | |
| language | No | Optional BCP-47 hint for transcription, e.g. en. | |
| quote_id | No | A `quote_id` from `quote`: charges exactly the quoted price (400 if unknown or expired). | |
| channel_url | No | `https://www.youtube.com/@handle`, `/channel/UC…`, or a playlist URL. | |
| channel_urls | No | Several channel or playlist URLs. | |
| collection_id | Yes | Collection to add the sources to. | |
| exclude_shorts | No | Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped. | |
| idempotency_key | No | Idempotency-Key for safe retries. | |
| min_duration_seconds | No | Skip expanded videos shorter than this many seconds. | |
| max_videos_per_channel | No | Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and openWorldHint=true; the description adds substantial non-obvious behavior: per-minute pricing with a 1-minute minimum, videos already in the collection are free, quote_id freezes the price (400 if unknown/expired), and write-scope API key requirement. This is exactly the 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?
Front-loaded with the charge-and-ingest action, then endpoint, pricing, workflow, and auth. Dense and mostly waste-free, though the quote-exactness point is stated twice ('Pass a quote_id...' and 'Prices are the service defaults; quote returns the exact price'), which is mild redundancy.
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 12-parameter mutating tool with no output schema, the description covers cost model, idempotency expectations, the polling contract for observing completion, and auth scope — enough for an agent to invoke and follow up correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds pricing meaning tied to the `quality` parameter ($0.01/min standard vs $0.03/min whisper) and clarifies quote_id's exactness guarantee, going beyond the schema's field-level notes.
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 specific verbs and resource: 'Expand the given YouTube URLs, charge for the new work and start an ingest job in an existing collection', plus the exact endpoint POST /v1/collections/{collectionId}/sources. The plural contrast with the sibling add_source is implicit in 'URLs'/'existing collection' and reinforced by the batch-oriented param set.
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 workflow guidance: pass a quote_id from quote to lock price, poll get_status every 10-30s until completed/partial/failed, and the auth scope required. It does not explicitly say when to prefer add_sources over the singular add_source sibling, which is the main gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free. Create an empty collection to add sources to later with add_sources. Maps to POST /v1/collections. Returns the collection and its collection_token (ct_…, shown once: store it; absent on an idempotent replay). API key required (the key's write scope). Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Display name for the collection. | |
| idempotency_key | No | Idempotency-Key for safe retries. |
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.
Fetch a single source and its processing status (type-specific provenance included). Maps to GET /v1/sources/{sourceId}. Requires the key's read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes | Source identifier, e.g. src_71b0e4. |
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.
Free. Get an ingest job started by transcribe or add_sources. Maps to GET /v1/jobs/{jobId}. Poll every 10–30 s until status is completed, partial or failed (terminal). completed means every accepted video is transcribed and indexed, so the collection is queryable; partial means some videos failed and were credited back (credited_usd); videos.completed / videos.failed count progress. Works with an API key or the collection's ct_ token as the bearer. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The `job_id` from `transcribe` or `add_sources`. |
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.
Free. Get the transcript of a video that is completed in one of your collections. Maps to GET /v1/videos/{youtubeId}/transcript. collection_id is required with an API key; with the collection's ct_ token as the bearer it defaults to the token's collection. format is json (segments with timestamps, default) or text (one [H:MM:SS] text line per segment). 404 when the video is not completed in that collection, or the transcript predates the transcript cache. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | json (default) or text. | |
| youtube_id | Yes | The 11-character YouTube video id, e.g. dQw4w9WgXcQ. | |
| collection_id | No | Collection the video is completed in (required with an API key). |
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.
Get usage and spend in dollars for the calling key: the account balance (wallet_usd), this period's spend (consumed_usd), query count, and budget remaining. Maps to GET /v1/usage. Requires the key's read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Billing period (default current). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds relevant behavioral context beyond annotations: the required `read` scope and the specific usage metrics returned. It does not contradict 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?
The description is compact and front-loaded: it starts with the core operation, enumerates the returned metrics, then adds the endpoint and required scope. Every sentence contributes useful information without repetition.
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, but the description explicitly lists the returned metrics, which compensates well. With the single optional parameter fully documented in the schema and annotations covering the read-only/open-world safety profile, an agent has enough information to invoke 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?
The schema has 100% description coverage for the single `period` parameter, including its enum values and default. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate because 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: get usage and spend for the calling key. It further specifies exactly which metrics are returned (wallet_usd, consumed_usd, query count, budget remaining) and maps the operation to GET /v1/usage, making the tool's purpose unambiguous relative to the sibling tools.
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 includes a key prerequisite—the calling key's `read` scope—which is useful context for whether the call can succeed. However, it does not explicitly say when to use this tool versus alternatives such as get_status, nor does it state when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the channels the calling key is scoped to. Maps to GET /v1/channels. Cursor-paginated. Requires the key's read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max items (default 25). | |
| cursor | No | Opaque pagination cursor from a prior response. |
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.
List the sources (video/document/website) in a channel, optionally filtered by type or status. Maps to GET /v1/channels/{channelId}/sources. Cursor-paginated. Requires the key's read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by source type. | |
| limit | No | Max items (default 25). | |
| cursor | No | Opaque pagination cursor. | |
| status | No | Filter by processing status. | |
| channel_id | Yes | Channel whose sources to list. |
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.
Run a retrieval-augmented query against a channel's indexed knowledge base and return a generated answer with citations. Maps to POST /v1/query. Requires the key's query scope and access to the channel. Charged: $0.02 flat per call by default. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The natural-language question. | |
| top_k | No | Chunks to retrieve (default 5). | |
| channel_id | Yes | Channel to query. The key must be scoped to it. | |
| session_id | No | Optional session for multi-turn continuity. | |
| source_types | No | Restrict retrieval to these source types. | |
| idempotency_key | No | Idempotency-Key for safe retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses authorization requirements (query scope + channel access) and the billing model ($0.02 flat per call, service defaults, with `quote` for exact pricing). That is substantive context the annotations do not carry; it stops short of describing rate limits or response shape details beyond 'answer with citations'.
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 tightly packed sentences, front-loaded with the action and resource, then prerequisites, then cost. The pricing sentence is slightly redundant ('by default' followed by 'Prices are the service defaults'), but each element is useful and no filler is present.
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 at a high level ('generated answer with citations'). Combined with endpoint, auth scope, and cost disclosure, an agent has enough to call it correctly; only the contrast with query_collection and pagination/answer structure 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%, so all six parameters including top_k defaults, session_id continuity, source_types restrictions and idempotency_key are already documented in the schema. The description adds no parameter-level syntax or format detail, which is the expected baseline when the schema does the work.
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+resource: 'Run a retrieval-augmented query against a channel's indexed knowledge base and return a generated answer with citations', plus the concrete endpoint POST /v1/query. It clearly identifies the channel scope (implying separation from query_collection), but never explicitly contrasts itself with the similarly-named sibling, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states prerequisites ('Requires the key's `query` scope and access to the channel') and routes pricing questions to the `quote` sibling when the default does not apply. It gives no guidance on when to pick this over query_collection or multi-turn session usage, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Charged: $0.02 flat per call by default, no token multiplier. Ask a question of a collection and get a generated answer with citations. Maps to POST /v1/collections/{collectionId}/query. Query a collection once get_status says completed. With an API key it needs the key's query scope. Without an API key this tool is payable in USDC via x402: the first call returns a payment-required result (isError with the payment requirements in structuredContent); an x402-aware MCP client signs and retries the same call with _meta['x402/payment'], and the receipt returns in the result's _meta['x402/payment-response']. Never pay again after a 409 (already presented) or 502 (settlement unknown) result. Keyless, only the address that paid for the collection may query it. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The natural-language question. | |
| session_id | No | Optional session for multi-turn continuity. | |
| collection_id | Yes | Collection to query. | |
| idempotency_key | No | Idempotency-Key for safe retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint/openWorldHint; the description goes far beyond them, disclosing pricing ($0.02 flat, no token multiplier), the full x402 keyless payment handshake, where payment requirements and receipts appear (`structuredContent`, `_meta`), and retry-safety rules. This is exactly the context an agent needs to invoke correctly and avoid double-paying.
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?
Every sentence carries load — purpose, pricing, prerequisite, auth, payment flow, failure handling — so little is wasted. However, leading with a billing line rather than the purpose is slightly off front-loading, and the payment-flow passage is dense enough to slow a skimming agent.
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 must carry the return story — and it does, covering the citation-bearing answer, the payment-required result, the retry receipt location, and terminal 409/502 outcomes. Nothing needed to call it successfully 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 the schema already documents all four parameters, and the description adds essentially no per-parameter detail beyond the URL-template mapping. Baseline 3 is the correct ceiling 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 — 'Ask a question of a collection and get a generated answer with citations' — and reinforces it with the exact underlying route POST /v1/collections/{collectionId}/query. That resource scoping (a collection, not a channel) cleanly distinguishes it from the sibling query_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?
It gives the prerequisite ('Query a collection once `get_status` says completed'), the required auth scope ('the key's `query` scope'), the keyless constraint, and routes to the sibling `quote` for exact pricing. It also names failure conditions with explicit follow-up rules ('never pay again after a 409 or 502').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free. Expand YouTube URLs exactly as an ingest would and return the price, the per-video lines and the per-source rejections. Maps to POST /v1/quote. $0.01/min standard, $0.03/min whisper by default, 1-minute minimum per video. The quote_id is valid for 15 minutes; pass it to transcribe or add_sources to be charged exactly this price. Pass collection_id to price against an existing collection (videos already in it are free). At least one of url, urls, channel_url, channel_urls. Requires the key's read scope. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | One YouTube URL (video, @handle, /channel/UC…, or playlist). | |
| urls | No | Several YouTube URLs. | |
| quality | No | Transcription quality (default standard). | |
| language | No | Optional BCP-47 hint for transcription, e.g. en. | |
| channel_url | No | `https://www.youtube.com/@handle`, `/channel/UC…`, or a playlist URL. | |
| channel_urls | No | Several channel or playlist URLs. | |
| collection_id | No | Price against this collection (videos already in it are free). | |
| exclude_shorts | No | Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped. | |
| min_duration_seconds | No | Skip expanded videos shorter than this many seconds. | |
| max_videos_per_channel | No | Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint/openWorldHint; the description adds substantial behavior beyond them: the call is free, pricing rates ($0.01/min standard, $0.03/min whisper), a 1-minute per-video minimum, the 15-minute quote_id validity, and the required `read` scope. It also clarifies that collection videos already present are free and that returned prices are exact service defaults.
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?
Purpose and the free/price hook are front-loaded, and each following sentence carries operational detail. There is mild redundancy between the opening 'Free' and the pricing sentence plus the closing 'Prices are the service defaults; quote returns the exact price', which could be tightened.
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, no-output-schema tool this covers what an agent needs: what it returns, that it costs nothing now, how the quote_id is consumed downstream, auth scope, and the mutual input constraint. Nothing material is left for the agent to infer before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description still adds meaning the schema lacks, notably the cross-field constraint that at least one of url, urls, channel_url, or channel_urls must be supplied (required is 0 in the schema) and how collection_id affects pricing. It does not restate the expansion defaults (exclude_shorts, max_videos_per_channel), which the schema already covers.
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 precise verb+resource (expand YouTube URLs exactly as an ingest would) and enumerates the return shape (price, per-video lines, per-source rejections), plus the backing endpoint POST /v1/quote. It is clearly separable from siblings like transcribe/add_sources because it is explicitly free and non-charging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the downstream alternatives (transcribe, add_sources) and the exact workflow: hold the quote_id for 15 minutes and pass it to be charged this price. It also states the at-least-one-of input requirement and the collection_id pricing option. It stops short of an explicit 'do not use this when you already have a quote / when you intend to charge immediately' exclusion, so it is clear context rather than full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask a question across about 490 curated 2026 conference talks and get a generated answer whose citations give each talk's video URL (with t=) and start_seconds, plus its conference, year and speakers. Optional filters: conference (one of ai-engineer-worlds-fair, ai-engineer-europe, kubecon-eu, google-cloud-next, microsoft-build, pycon-us, google-io, code-with-claude, openai-devday), year, and speaker (part of a name, case-insensitive; speakers are known for about half the talks, so a speaker filter misses the rest). A filter that matches no talk answers answer: null and costs nothing. Maps to POST /v1/search/talks. Charged: $0.02 flat per call by default, or free within the daily free allowance. With an API key it needs the key's query scope. Without an API key this tool is payable in USDC via x402: the first call returns a payment-required result (isError with the payment requirements in structuredContent); an x402-aware MCP client signs and retries the same call with _meta['x402/payment'], and the receipt returns in the result's _meta['x402/payment-response']. Never pay again after a 409 (already presented) or 502 (settlement unknown) result. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Conference year, e.g. 2026. | |
| speaker | No | Part of a speaker name, case-insensitive. | |
| question | Yes | The natural-language question. | |
| conference | No | Conference slug: ai-engineer-worlds-fair, ai-engineer-europe, kubecon-eu, google-cloud-next, microsoft-build, pycon-us, google-io, code-with-claude, openai-devday. | |
| idempotency_key | No | Idempotency-Key for safe retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description discloses pricing, free allowance, API-key scope requirements, x402 payment flow, payment-required results, retry metadata, and when not to pay again after 409 or 502 errors. This is unusually rich behavioral context for successful invocation.
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 long but front-loads the core purpose and output, then proceeds through filters, no-match behavior, endpoint mapping, and payment handling. Every sentence carries operational value, including the x402 retry guidance, so the density is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains the return shape: a generated answer plus citations containing video URL with t=, start_seconds, conference, year, and speakers. It also covers filters, no-match behavior, pricing, auth, and payment flow, leaving no major invocation 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 coverage is already 100%, so the baseline is 3, but the description adds a meaningful semantic caveat that speaker is a partial case-insensitive name and only known for about half the talks. It also restates filter options and their slugs, though idempotency_key is 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?
The description gives a specific verb and resource: asking a question across about 490 curated 2026 conference talks and getting a generated cited answer. It clearly states scope and output, though it does not explicitly distinguish this tool from siblings such as query_collection or query_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?
It gives clear usage context: use it to ask natural-language questions over 2026 conference talks, with optional conference, year, and speaker filters. It also warns that speaker filters miss about half the talks and that a no-match filter returns answer: null at no cost, but it does not name alternative tools or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Charged. Create a collection and start an ingest job for the given YouTube URLs in one call. Maps to POST /v1/transcribe. $0.01/min standard, $0.03/min whisper by default, 1-minute minimum per video. Pass a quote_id from quote to be charged exactly that price. Returns job_id, collection_id and collection_token (ct_…, shown once: store it; it reads this collection without an API key). Poll get_status every 10–30 s until status is completed, partial or failed; completed means every accepted video is transcribed and indexed, so the collection is queryable. With an API key it needs the key's write scope. Without an API key this tool is payable in USDC via x402: the first call returns a payment-required result (isError with the payment requirements in structuredContent); an x402-aware MCP client signs and retries the same call with _meta['x402/payment'], and the receipt returns in the result's _meta['x402/payment-response']. Never pay again after a 409 (already presented) or 502 (settlement unknown) result. Keyless transcribe takes one channel-like source and at most 3 videos. Prices are the service defaults; quote returns the exact price.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | One YouTube URL (video, @handle, /channel/UC…, or playlist). | |
| urls | No | Several YouTube URLs. | |
| title | No | Title for the new collection (default: generated). | |
| quality | No | Transcription quality (default standard). | |
| language | No | Optional BCP-47 hint for transcription, e.g. en. | |
| quote_id | No | A `quote_id` from `quote`: charges exactly the quoted price (400 if unknown or expired). | |
| channel_url | No | `https://www.youtube.com/@handle`, `/channel/UC…`, or a playlist URL. | |
| channel_urls | No | Several channel or playlist URLs. | |
| exclude_shorts | No | Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped. | |
| idempotency_key | No | Idempotency-Key for safe retries. | |
| min_duration_seconds | No | Skip expanded videos shorter than this many seconds. | |
| max_videos_per_channel | No | Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and openWorldHint=true; the description carries the real behavioral load. It discloses pricing ($0.01/min, $0.03/min whisper, 1-min minimum), the write-scope auth requirement, the full x402 keyless payment handshake, the never-pay-again rule for 409/502, and the fact that collection_token is shown once and grants keyless read. This is exactly the beyond-annotations context the dimension rewards.
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 pricing, and essentially every sentence carries non-redundant information (pricing, polling, payment flow, retry guard). It is dense and unparagraphed, and the opening 'Charged.' fragment is cryptic in isolation, which costs a point, but there is little padding to cut.
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 12-parameter, no-output-schema, paid, two-auth-mode tool, the description covers what an agent must know: return values (job_id, collection_id, collection_token), terminal statuses, polling cadence, auth requirements, and payment semantics. Nothing critical is left to inference.
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 3 baseline applies, but the description adds meaning the schema does not: quality drives the price differential (standard vs whisper), keyless mode restricts url/urls to one source and at most 3 videos, and quote_id yields an exactly-quoted charge. These constraints are behavioral couplings across parameters that the schema alone would not convey.
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) on a specific resource (YouTube URLs) in one call, and disambiguates from siblings like create_collection and add_source by naming the combined behavior. The 'Maps to POST /v1/transcribe' line pins the operation without ambiguity.
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 routing: use this for one-shot create+ingest, poll with get_status every 10-30s, and pass a quote_id from quote when you want an exact price. It also states the keyless constraint (one channel-like source, max 3 videos). It stops short of explicitly saying when to prefer create_collection + add_source for adding to an existing collection, so the sibling exclusion is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
search_talksadd_sources3 fields changedInput schema / properties / exclude_shortsAdded value: +{
+ "description": "Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped.",
+ "type": "boolean"
+}Input schema / properties / max_videos_per_channel / descriptionPrevious value: -"Newest-first cap applied to each channel or playlist (default 25)."New value: +"Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap."Input schema / properties / min_duration_secondsAdded value: +{
+ "description": "Skip expanded videos shorter than this many seconds.",
+ "maximum": 14400,
+ "minimum": 0,
+ "type": "integer"
+}quote3 fields changedInput schema / properties / exclude_shortsAdded value: +{
+ "description": "Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped.",
+ "type": "boolean"
+}Input schema / properties / max_videos_per_channel / descriptionPrevious value: -"Newest-first cap applied to each channel or playlist (default 25)."New value: +"Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap."Input schema / properties / min_duration_secondsAdded value: +{
+ "description": "Skip expanded videos shorter than this many seconds.",
+ "maximum": 14400,
+ "minimum": 0,
+ "type": "integer"
+}transcribe3 fields changedInput schema / properties / exclude_shortsAdded value: +{
+ "description": "Skip videos of 3 minutes or less when expanding a channel or playlist (default true); explicit video URLs are never skipped.",
+ "type": "boolean"
+}Input schema / properties / max_videos_per_channel / descriptionPrevious value: -"Newest-first cap applied to each channel or playlist (default 25)."New value: +"Newest-first cap on eligible videos per channel or playlist (default 25); Shorts and videos below min_duration_seconds are skipped before the cap."Input schema / properties / min_duration_secondsAdded value: +{
+ "description": "Skip expanded videos shorter than this many seconds.",
+ "maximum": 14400,
+ "minimum": 0,
+ "type": "integer"
+}add_sourceadd_sourcescreate_collectionget_sourceget_statusget_transcriptget_usagelist_channelslist_sourcesquery_channelquery_collectionquotetranscribeSearch and query the transcripts of YouTube expert channels you follow, with cited answers.
Read YouTube transcripts and search what people say across 425k videos. Free API key.
Pre-computed answers with sources and confidence, paid per call over x402 (USDC on Base).
Clean transcripts of any YouTube video with captions. Pay per call with x402 USDC, no API key.
Add one secure layer between your agents and this server.
