Spoken

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

Annotations only cover safety/idempotency; the description adds substantive behavior an agent cannot infer: the follow persists regardless of fetch activity, does not consume one of five automatic slots, does not spend credits, and defines what counts as 'new' for a never-fetched show. That is exactly the beyond-annotations context this 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?

Four short sentences, action first, then semantics, then cost. Every sentence carries information, though the clause about new-episode counting for unfetched shows is dense and 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?

An output schema exists so return values need no explanation, and the description covers the remaining unknowns an agent would need: persistence semantics, slot accounting, credit cost, and the id's source. Nothing material is missing for a single-parameter mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds provenance ('from search_podcasts') that tells the agent where a valid id originates rather than just its type. It does not add format or validation detail beyond that, so 4 rather than 5.

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 ('Declare a follow for a show') and adds a second, less obvious effect ('or clear a mute'), which the agent would not guess from the name. It names siblings (search_podcasts, unfollow_podcast) so it can be told apart from them. The dual behavior is slightly muddled but the core action is unmistakable.

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

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

Explicitly tells the agent where the argument comes from ('Pass a podcast_id from search_podcasts') and when this tool is the right one: it contrasts with the five automatic slots and with unfollow_podcast. No explicit 'when not to use' beyond the sibling reference, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds genuinely new behavioral context not present in annotations: 'Does not consume credits,' which is the key cost concern for a metered API. It stops short of stating auth requirements or rate limits.

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

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

Two sentences, no filler. The scope of returned data is front-loaded and the cost caveat is placed where it will be read before invocation.

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 no-parameter read tool with an output schema already defining the return shape, the description supplies everything an agent needs: what it returns, that it targets the configured API key, and that it is free. Return-value detail is correctly delegated to the output schema.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly does not invent parameter guidance where none is needed.

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

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

States a specific verb ('Check') and names the exact resources returned: credit balance, account email, and recent usage. It is unmistakably distinct from the podcast-management siblings (list_episodes, search_podcasts, follow_podcast), so an agent can route without opening any schema.

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

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

Usage is implied by the purpose (check balance before making calls), and 'for the configured API key' clarifies the scope, but there is no explicit when-to-use/when-not guidance or named alternative. Adequate for a zero-parameter read tool, but no routing instructions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: the 1-credit cost on first fetch, free repeat fetches, and no charge on errors. That is valuable billing/retry semantics, though return structure beyond format is not detailed.

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 tight sentences with no filler. The core action and output format are front-loaded, and the cost/retry caveat follows as supporting detail.

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

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

With no output schema, the description compensates by describing the return format (Markdown, real speaker names, timestamps), the input provenance, and the billing behavior. Nothing an agent needs to call 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?

Only one parameter and schema description coverage is 100% — the schema already documents that episode_id is the id returned by search_podcasts. The description merely repeats that provenance, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (podcast episode's transcript) plus the output shape (clean Markdown with real speaker names and timestamps). It also names the sibling tool (search_podcasts) that produces the required input, so an agent can distinguish it from list_episodes or get_balance at a glance.

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

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

Explicitly tells the agent where the episode_id comes from (search_podcasts), establishing the prerequisite workflow step. It does not state any when-not-to-use condition or alternative transcript sources, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds behavior none of them express: it consumes no credits itself, transcribing returned episodes costs 1 credit each, repeat fetches are free, and the agent should verify the key has enough credits before looping. This credit/cost disclosure is genuinely load-bearing 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?

Front-loads what the tool returns and its ordering, then appends the credit caveat. Four sentences all carry weight, though the credit-warning clause is slightly verbose relative to the rest.

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 an output schema present, return values need not be enumerated, yet the description still summarizes them (id, title, date). For a single-param read tool it supplies the upstream source, downstream consumer, and cost model — everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single podcast_id parameter is already documented as 'the podcast_id field from a search_podcasts result'. The description repeats this provenance without adding format, validation, or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('List a podcast's entire back-catalog') with scope and ordering ('every episode, newest first'), which cleanly distinguishes it from the sibling list_new_episodes. An agent can identify it without opening the schema.

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

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

Explicitly routes the agent: pass a podcast_id from a search_podcasts result, and fetch episodes with get_transcript to 'transcribe a whole show'. It names the upstream and downstream tools but never states the inverse condition (e.g. when to prefer list_new_episodes over this back-catalog listing), so it stops short of 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the description does not consume credits, the demo key has nothing to follow, the 5-auto / 25-explicit follow caps, the 180-day window, and that muted shows appear in a separate section. These are non-obvious traits not derivable from the schema or 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?

Most sentences carry real payload (source semantics, caps, credit cost, alternative tool), but the opening sentence is confusingly phrased and the 'every charged fetch makes its show a follow' clause takes a second read to parse. Information is not cleanly front-loaded around the core action of listing.

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

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

An output schema exists, so return values need not be explained, and the description covers the important ambient facts: follow sources, muted separation, credit cost, and where to go next. The only gap is the fuzzy lead sentence, which slightly obscures what exactly is returned as the primary list.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate at the parameter level; the baseline for a parameterless tool is 4. The description correctly implies a bare, no-argument call.

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 identifies the resource (the shows this key is kept current on) and, more usefully, defines what a 'follow' actually means here — automatic follows from charged fetches (source 'fetch') versus declared follows via follow_podcast (source 'explicit'). The opening clause 'The shows this key is kept current on' is grammatically awkward and never states a clean verb like 'lists', but the follow semantics make the resource unambiguous and distinguishable from siblings.

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 explicitly routes the agent to two siblings: follow_podcast to declare additional follows, and list_new_episodes to see what is new on the followed shows. It also notes muted shows are listed separately. It does not state an explicit when-not-to-use condition beyond the demo-key caveat, so it falls short of full 5-level routing.

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 confirm it is a safe read, but the description adds non-obvious behavior beyond them: the 90-day window, the 10-per-show cap, the floor-raising side effect of get_transcript, hourly refresh latency, and zero credit cost. These are exactly the traits an agent needs and cannot get from annotations or schema.

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

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

Front-loaded with the core answer ('What is new...') and each sentence carries distinct operational detail. It is slightly dense and could be split for readability, but 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?

Given the output schema exists, the description wisely omits return-shape details and instead covers the entire operational contract: filtering rules, caps, costs, cursoring side effects, and freshness latency. Nothing an agent needs in order to call 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?

There are zero parameters, so the baseline is 4. The description is silent on parameters, which is correct since there are none, but it also doesn't add semantic meaning (no parameters exist to clarify).

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 resource (new episodes on followed shows) and goes far beyond the name by specifying the exact scope: last 90 days, newer than the newest already fetched, up to 10 per show, transcript_url required. An agent can distinguish this from list_episodes and list_following immediately.

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 names the follow-up tool (get_transcript) and its cost, and describes the cursoring behavior that dictates when to call again. It also sets a precondition (hourly refresh) that explains when calling would be futile.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond annotations: the call does not consume credits, which matters for a credit-metered service. It could go further on result limits or pagination, but the credit disclosure is real added value.

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

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

Four short sentences, front-loaded with the primary capability, then return fields, then chaining guidance, then the cost caveat. No filler and nothing out of 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?

For a one-parameter search tool with an output schema already present, the description supplies everything else an agent needs: accepted input forms, key return fields for extraction, downstream tool chaining, and the credit cost. 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% with a single documented 'query' parameter, so the schema already carries the load. The description echoes that dual free-text/URL intent and adds platform examples (Spotify, YouTube) slightly beyond the schema's example, but adds no format or parsing rules, so baseline 3 is right.

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 (search) and resource (published podcast episodes) plus the two accepted input modes (free-text query or pasted episode URL). Distinguishes itself from siblings like list_episodes and get_transcript by describing what it returns and how it differs from the back-catalog listing.

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

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

Gives clear context for the two invocation modes and explicitly routes follow-up work to get_transcript (via id) and list_episodes (via podcast_id). No explicit 'do not use this when...' exclusion, so it stops short of the top score.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description adds non-obvious semantics: the show leaves the followed list AND later fetches will not re-add it, that follow_podcast reverses the effect, and that no credits are consumed. That is real behavioral context (persistence, reversibility, cost) beyond the structured hints.

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

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

Three short sentences, front-loaded with the effect, then the reversal, then the id source and cost note. Every clause carries information an agent needs; nothing is padding.

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

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

An output schema exists so return values need not be described. Effect, persistence, reversibility, id provenance, and cost are all covered, which is everything needed to invoke this one-parameter tool correctly.

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

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

Schema coverage is 100% and there is a single required parameter already documented as coming from list_following or search_podcasts. The description's 'Pass a podcast_id from list_following' repeats, and slightly narrows, what the schema already states, adding no new syntax or format detail.

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 concrete verb+resource ('Mute a show: it leaves the followed list') and explicitly names the sibling that undoes it (follow_podcast), so an agent can distinguish it from follow_podcast without opening schemas. The word 'Mute' is slightly off-register versus the tool name 'unfollow', but the very next clause resolves the effect unambiguously.

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 context: the reverse operation is follow_podcast, and the id comes from list_following. It does not spell out an explicit when-not-to-use or a broader alternative comparison, but for a single-purpose toggle the guidance is sufficient.

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