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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context beyond those: it relies on crawl history and reports specific diagnostic signals such as failed fetches, parse errors, last HTTP status, last successful read, and dead/duplicate status. This gives the agent a concrete model of what the call will reveal without contradicting 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 sentences with no filler. The first sentence states what it does; the second removes a common assumption about ownership; the third gives a concrete use case. The most important information is front-loaded and every sentence earns its place.

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

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

For a single-parameter diagnostic tool, the description is complete: it identifies the input flexibility, the diagnostic evidence returned, and a motivating scenario. There is no output schema, but the description enumerates the key result categories, so an agent can understand what to expect. Minor gaps like not-found or invalid-input behavior are not critical for this tool.

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

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

The input schema covers 100% of the single parameter and already states that 'show' can be a feed id, RSS URL, podcast GUID, Apple Podcasts URL, or iTunes id, with auto-detection. The description adds little parameter-specific detail because the schema is already rich, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb, 'Diagnose', and names the exact resource, a podcast feed via the Podcast Index crawl history. It enumerates concrete symptoms (failed fetches, parse errors, HTTP status, last successful read, dead/duplicate) that distinguish this from generic feed lookups, and the wording clearly separates it from sibling tools like get_podcast or status.

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 gives a clear trigger: run it before blaming a host for a drop in downloads. It also tells the agent that the tool works on any feed in the index, removing an ownership prerequisite. However, it does not name alternatives or say when not to use it, so some routing judgment is still left to the agent.

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses substantial behavior: grouping by show, newest-first ordering, including roles, flagging likely self-appearances, and restricting to Podcasting 2.0 person tags. It also explains how to interpret empty results, which is valuable context the annotations do not convey.

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

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

The description is tightly structured: the first sentence states the core result and ordering, the second gives the research use case, and the third covers the key limitation and interpretation. Every sentence earns its place with no filler or 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?

Because there is no output schema, the description carries the burden of explaining the return shape, and it does: episodes credited, grouped by show, newest first, with roles, and own-show flagging. The PC2.0 coverage limitation and empty-result interpretation make the tool's real-world behavior clear enough for an agent to call it and judge the result 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 input schema covers 100% of parameters with descriptions, so the description does not need to add much. The description reinforces that 'name' refers to the credited person and that 'max' limits episodes considered before grouping, but it does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it finds every episode a named person is credited on, grouped by show and ordered newest first, with their role. It also frames the purpose as guest research ('who has had this person on'), which helps distinguish it from generic episode search, though it never names a sibling tool like search_episodes_by_person.

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 gives clear usage context, explicitly saying this is for guest research and listing the questions it answers. It also gives an important limitation: only shows publishing Podcasting 2.0 person tags are found, so an empty result is not evidence of absence. However, it does not provide explicit when-not-to-use guidance or direct the agent to an alternative sibling tool.

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, and non-destructive behavior. Beyond that, the description discloses meaningful behavioral details: it filters to alive, recently-published, episode-rich, contactable shows; it ranks by recent activity rather than relevance; and it describes what each result contains. This goes well beyond the annotation coverage.

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 four sentences, front-loads the core purpose, and every sentence earns its place: purpose, contrast with plain search, result contents, and ranking rationale. There is no fluff or redundant restatement of the schema.

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?

Even without an output schema, the description tells the agent what results look like, how they are ordered, and what criteria were used to select them. Combined with fully documented parameters, this gives the agent enough to call the tool and interpret results correctly.

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

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

Schema description coverage is 100%, so the schema already explains each parameter, including defaults and their filtering intent. The description loosely echoes 'real episode count' and 'publishing recently' but does not add new parameter-level meaning or syntax details beyond what the schema provides.

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 uses a specific verb and resource: 'Search for shows on a topic and keep only the ones worth approaching.' It clearly defines the tool's filtering intent and distinguishes it from a plain search, so an agent immediately understands this is the lead-qualification variant rather than a generic search.

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 gives clear usage context: this is for guest outreach where dead or dormant shows should be excluded. It contrasts with 'a plain search' that returns the whole index, implying when the unfiltered alternative is more appropriate. However, it does not explicitly name a sibling tool or state a definitive when-not-to-use condition.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful non-obvious traits: it does not fetch transcript files, it scans only recent episodes, and it reports both transcripts and chapters. The final heuristic about shows is useful, though slightly over-generalized; 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?

Three sentences with distinct jobs: core function, usage direction, and decision heuristic. The most important information is front-loaded, and there is 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 simple two-parameter discovery tool with strong annotations, the description covers scope, side effects, and when to call it. It does not specify the exact response shape, but no output schema is present and the description's 'report which...' gives enough of a contract for an agent to decide next steps.

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

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

Schema description coverage is 100%, with both show and max already explained in the input schema. The tool description adds no parameter-level detail beyond 'recent episodes', so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Scan a show's recent episodes and report which of them publish a transcript or chapters'. It also distinguishes the tool from siblings by saying it does this 'without fetching any of the files' and by naming get_transcript/search_transcript.

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 gives an explicit when-to-use rule: 'Call this before get_transcript or search_transcript on an unfamiliar show', with the rationale that it is 'one request' versus discovering the answer through a 'failed lookup per episode'. This makes the choice between tools clear.

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

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

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral context: excluded chapters are intentionally retained and labelled rather than dropped, with a clear rationale about sponsor reads and timeline accuracy. It also discloses that chapters are optional and commonly absent, which is not visible 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?

The description is front-loaded with the core purpose, then efficiently adds usage context, behavioral nuance, and a caveat about availability. Every sentence contributes necessary information, with no redundant filler or restating 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 a single well-documented parameter and strong annotations covering safety and idempotency, the description fully covers what the agent needs to select and invoke the tool correctly. It explains what data is returned, how excluded chapters behave, and how this relates to transcripts, leaving no major gaps despite the lack of an 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?

Schema description coverage is 100%, so the only parameter, episode_id, is already documented as a Podcast Index episode id. The description confirms the resource is tied to an episode but does not add extra format, validation, or usage details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description clearly states a specific action ('Fetch and read'), a specific resource ('chapter list a publisher attached to an episode'), and the contents (titles, start times, images, links). It also implicitly distinguishes itself from the transcript-related sibling tools by framing chapters as the publisher's table of contents and cheaper than reading the transcript.

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 gives clear context for when to use the tool: when the question is 'what is in this episode and when', and notes it is cheaper than reading the transcript. It also cautions that chapters are optional and most episodes have none, which helps agents set expectations, though it does not explicitly name alternatives or provide a formal when-not-to-use rule.

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 carry the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), and the description adds compatible behavioral detail: the contents of the full episode object and the non-obvious default that a bare GUID resolves to 'whichever episode the index finds first.' That ambiguity disclosure is real value beyond what annotations provide.

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 sentences, every one load-bearing: scope, identifier preference, and the ambiguity caveat. Purpose is front-loaded, and there is no filler, no repetition of the title, and no restatement of annotation fields.

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

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

For a read-only lookup with three optional parameters and no output schema, the description covers both what is returned and how to disambiguate the target episode. The component list partially substitutes for the missing output schema. It could go further by naming the piecewise siblings explicitly, but nothing an agent needs to make a correct call is absent.

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

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

Schema coverage is 100% and the schema already documents all three parameters well, so the baseline is 3. The description adds the episode_id preference ordering ('fastest path') and spells out the consequence of omitting show when using a GUID, which goes beyond the schema's 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 a specific verb and resource ('get one episode') and enumerates the exact contents returned: description, credited people, soundbites, value block, transcript, and chapter pointers. This enumerated scope clearly separates it from specialized siblings like get_transcript, get_chapters, get_soundbites, and get_value_block, as well as the plural get_episodes.

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 call-time guidance: prefer the Podcast Index episode_id as the 'fastest path,' and only use a GUID together with a show. It explains the GUID uniqueness constraint and the fallback behavior if show is omitted. It does not explicitly name alternative tools or state when-not-to conditions, which keeps it from 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 convey read-only, idempotent, and non-destructive behavior. The description adds useful behavioral detail: episodes are sorted newest first, any show identifier form is accepted/detected, and each episode exposes its Podcasting 2.0 extras via a 'has' attribute. These go beyond the annotations without contradicting them.

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 sentences deliver the core purpose, ordering, identifier flexibility, payload hint, and a concrete usage recommendation. The most important facts are front-loaded, 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 a three-parameter, one-required-parameter tool with no output schema, the description covers purpose, ordering, identifier formats, an important return attribute ('has'), and parameter selection guidance. It could be slightly stronger by explicitly noting the response is a list and how many episodes are returned by default, but the schema covers max, so the gap is minor.

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 already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful guidance beyond the schema by recommending 'since' over a large 'max' for recent episodes and by clarifying that the 'show' identifier form is auto-detected so callers should pass what they have without converting.

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 clearly states the tool returns episodes for one show, newest first, and specifies that it accepts multiple identifier forms. It is distinguishable from siblings like get_episode (single episode) and get_recent_episodes (not tied to one show), though it does not explicitly name them.

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 gives clear context for using the tool and even provides internal guidance on preferring 'since' over a large 'max' for recent episodes. However, it never explicitly says when to prefer this tool over sibling tools such as get_episode or get_recent_episodes, leaving that 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 already cover readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context not in annotations: why the split may differ from the show's, the override mechanism, and that the endpoint only accepts the exact pair of GUIDs. No contradictions.

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 sentences, each earning its place: first defines the resource, second explains why it exists, third states the requirement. Slightly awkward phrasing in the first sentence ('The value block for...') but no wasteful content.

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

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

For a simple read-only tool with two well-documented parameters and no output schema, the description provides enough context to understand what data is returned and why both IDs are necessary. It does not detail the return format, but annotations and the title compensate adequately.

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 with source hints. The description adds value by emphasizing that both GUIDs are required together and that this pair is the only accepted combination, which clarifies the relationship between parameters 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?

The description clearly identifies a specific resource: the payment split/value block for a single episode. It explains the purpose ('see who was cut in on a particular conversation') and explicitly distinguishes this from the show-level value block ('can differ from the show's'), which differentiates it from sibling get_value_block.

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 gives concrete context for when to use it: when a publisher overrides the split per episode and you need to see who was paid on a particular episode. It also states the prerequisite of needing both GUIDs, but does not explicitly name an alternative tool or say 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.

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that, such as the interpretation of the gap between total feeds and feeds active in 30 days, and that value-block counts are included. No contradiction with 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 short, front-loaded with the core purpose, and every sentence earns its place. The first sentence enumerates the concrete metrics, and the second adds a useful interpretive lens without 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?

For a simple, parameterless, read-only stats tool with no output schema, the description is complete enough: it enumerates all key data points returned and explains what the activity numbers mean. An agent can decide when to call it and what to expect from the result.

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 has zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The description instead focuses on the returned metrics, which is appropriate for a parameterless endpoint.

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 clearly states what the tool reports: index size and activity with specific metrics like total feeds, total episodes, and recency buckets. This is distinguishable from sibling tools by content, though it does not explicitly name an alternative or contrast itself with the 'status' sibling.

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 intended use is implied: call this when you need a picture of index size and how many feeds are currently active. However, it gives no explicit when-to-use or when-not-to-use guidance, nor does it name any alternative among the many sibling tools.

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

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

Annotations already provide read-only and open-world hints. The description adds behavior beyond that: the list is small and fast-moving, a handful of results is normal, an empty response is possible, and each entry contains start time, end time, and status. This gives the agent expectations that are not present in the 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?

Three sentences with the main behavior front-loaded in the first sentence. Each remaining sentence adds non-redundant value: expected list size/volatility and the fields carried by entries. There is no filler or 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?

For a simple read-only list tool with one optional parameter and no output schema, the description covers scope, result-size expectations, the possibility of an empty list, and the entry fields. It does not specify ordering or pagination, but these are minor gaps given the low complexity and fast-moving nature of the data.

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 one parameter, max, and the input schema fully documents it with a default of 20, minimum/maximum bounds, and a description. With 100% schema coverage, the description does not need to add parameter-level detail, so the baseline score of 3 applies.

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

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

The description names a specific verb and resource: getting episodes currently marked live across the whole index, and even identifies the source data as the Podcasting 2.0 liveItem tag. This clearly distinguishes the tool from sibling episode-listing endpoints like get_recent_episodes or get_reending.

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 is clear that this should be used when the task calls for currently-live episodes across the entire index, and it sets expectations with warnings about small, fast-moving results and possible empty lists. It does not explicitly name alternative tools or when-not conditions, so it has clear context but no formal exclusion 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?

With readOnlyHint=true and destructiveHint=false, the safe read nature is already covered by annotations. The description adds valuable behavioral context beyond that: results are newest-first, the pool contains much noise, and many feeds are empty, abandoned, or automated. This helps agents interpret results correctly.

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 sentences, each earning its place: the core behavior, the key distinction from episodes, and the practical noise warning. The most important information is front-loaded, and there is no filler or repetition of schema details.

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

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

For a simple read-only list endpoint with fully documented parameters, the description covers purpose, ordering, and data-quality expectations. It does not describe return fields, but there is no output schema and the resource is clear enough from the name and description. Minor missing context: no mention of how `since` interacts with the feed-creation date, though the schema handles the parameter itself.

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 three parameters (max, since, oldest_first) are already fully documented in the schema. The description adds no additional parameter-level meaning or examples, which matches the baseline expectation 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 resource ('feeds added to Podcast Index for the first time') and a clear ordering ('newest first'). It also distinguishes itself from episode-oriented tools by emphasizing 'genuinely new podcasts rather than new episodes,' which prevents an agent from confusing it with recent-episode endpoints.

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 gives an explicit use case: 'the tool for spotting a launch.' It also sets expectations about noisy results. It does not name alternative sibling tools or explicitly state when not to use it, so it falls short of full alternative 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 already carry the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), lowering the bar. The description adds meaningful context — the 'newest first' ordering and the semantic distinction that these are first-time adopters — but discloses nothing beyond that, such as result shape or how the result set behaves as an open world over time. No contradiction with 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?

Two sentences, roughly 35 words, with the core result statement front-loaded and the second sentence earning its place by clarifying intent ('first time' adoption). No fluff or repetition of what the title already states.

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

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

For a simple read-only list tool with two fully documented optional parameters, the description plus annotations cover safety, scope, and ordering. The only minor gap is the lack of any return-format hint — there is no output schema, and the description assumes an agent will infer that a list of feed objects comes back.

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% — both max and since are fully documented with defaults and timestamp semantics, including the negative-since special case. The description itself adds no parameter-level 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?

The description states a specific verb and resource — returns feeds that recently added a value block — and immediately clarifies the scope ('shows adopting listener payments for the first time, newest first'). This semantic positioning implicitly distinguishes it from siblings like get_new_feeds and list_value_podcasts, but it never names an alternative, so the differentiation is left to inference rather than made explicit.

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 'growth edge... adopting listener payments for the first time' framing gives an agent a sense of when the tool is relevant, but there is no explicit when-to-use, when-not-to-use, or named alternative like get_new_feeds or get_recent_feeds. Context is implied 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 mark the tool read-only and idempotent, and the description adds meaningful behavioral context beyond that: it resolves multiple identifier formats, detects the form automatically, and returns a specific set of show details. No contradictions with 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 sentences with no filler: first states return value, second states accepted inputs and auto-detection, third gives usage route versus sibling. Front-loaded with the most important 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?

For a single-parameter read-only tool, the description fully explains input flexibility, return contents, and when to use it. Annotations cover safety, and no output schema exists, so the description adequately covers what an agent needs to invoke 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%, so the baseline is 3. The description reinforces the parameter semantics and adds the useful directive to 'pass what you have rather than converting it,' which goes beyond the schema by clarifying that conversion is unnecessary.

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?

Description states a specific operation: retrieve everything Podcast Index knows about one show, and enumerates the exact fields returned (metadata, category, episode count, last publish, Podcasting 2.0 features). It explicitly distinguishes itself from search_podcasts, so an agent can tell them apart 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?

Provides explicit when-to-use guidance: 'Start here when you already know the show; use search_podcasts when you are still looking for it.' It also clarifies that any identifier form is accepted and tells the agent not to convert identifiers, removing a likely error.

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, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: batching behavior, rate-limit sensitivity, and the endpoint's exclusive identifier type. No contradictions with 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 sentences with no filler. Each sentence has a distinct job: stating what it does, guiding when to use it, and constraining the accepted identifier. The most important information (purpose and batching advantage) is front-loaded.

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 one-parameter, read-only tool with rich annotations and full schema coverage, the description covers what, when, why, and the critical input constraint. The absence of an output schema makes the lack of return-format details acceptable; the agent has everything needed to call it correctly.

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

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

The schema already provides 100% coverage for the single parameter, including the array limits and a description. The description adds extra semantic value by explicitly excluding feed ids and explaining why GUIDs are required, which prevents a common misuse even with the schema present.

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 ('Look up'), a clear resource ('many shows'), and the key identifier ('by podcast GUID'). It also distinguishes this tool from its sibling get_podcast by emphasizing the batch aspect ('in one request'), making its purpose unambiguous.

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 tells agents when to use this tool instead of the alternative ('instead of calling get_podcast in a loop whenever you have more than three or four') and explains why ('one request rather than one each, which matters against a rate limit and is far faster'). It also states a clear exclusion ('Only accepts podcast GUIDs, not feed ids'), preventing incorrect usage.

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 carry the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). The description adds meaningful domain context — what 'medium' signifies and that the index spans music, video, film, audiobook, and more — which complements the openWorldHint. However, it doesn't disclose return-format or pagination behavior; the schema handles defaults via 'max'. This matches the get_calls calibration: annotations cover the burden, description adds moderate 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?

Three sentences, each earning its place: the first states the core function, the second explains the domain concept, the third gives the use-case. The essential scoping ('of one Podcasting 2.0 medium') is front-loaded, and there is zero filler or repetition of schema content.

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?

Complete for a filtered-list tool of this simplicity: the schema fully documents both parameters, annotations carry the read-only safety profile, and the description explains the domain concept, the use case, and the contrast with search. An agent has everything needed to select and invoke it correctly; no output schema exists and none is required to understand that it lists feeds.

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%, documenting both 'medium' and 'max' with defaults and enum ranges, so the baseline is 3. The description adds a conceptual layer — 'The medium says what a feed actually contains' — which deepens the meaning of the medium parameter and is reinforced by the enum values. This is useful but not a substantial compensation beyond what the schema already provides.

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 ('feeds'), and scope ('of one Podcasting 2.0 medium'). The description actively differentiates from the search siblings by explaining that the index contains far more than talk shows and that this tool surfaces content a normal search buries — a genuine distinction from search_podcasts and get_recent_feeds.

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 use directive: 'Use this to find content types that a normal podcast search buries, such as audiobooks or serialised film.' This clearly states when to choose this tool over the search path, with concrete examples. It stops short of naming the exact sibling (search_podcasts) or stating when to prefer other siblings like list_categories, but the primary ambiguity is resolved.

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?

The description adds meaningful behavioral detail beyond the annotations: results are genuinely random, never cached, and repeated calls yield different episodes. This complements the readOnlyHint and idempotentHint=false annotations without contradicting them.

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 sentences, each earning its place: the first defines the operation, the second explains why it is useful, and the third discloses a non-obvious behavior. The most important information is front-loaded.

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

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

For a read-only tool with four optional parameters and complete schema documentation, the description is sufficient to select and invoke it correctly. It explains the random behavior and the sampling use case, though it does not describe the response shape, which is acceptable given no output schema is provided.

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 parameters are already well documented. The description adds conceptual context around language and category filtering, but does not provide additional syntax, defaults, or format details beyond what the schema already gives.

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 clearly states a specific action and resource: retrieving random episodes from across the whole index with optional filters. It explicitly contrasts with ranked results, which helps distinguish it from tools like get_trending and get_recent_episodes even without reading their 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?

The description gives a clear use case: sampling what a category actually contains rather than what popular shows look like. It implies when to choose this tool over ranked or recent alternatives, though it does not name specific sibling tools or state explicit when-not-to-use 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?

注释已表明这是只读、非破坏性操作，描述在此基础上增加了行为特性：这是实时发布的‘消防水龙头’，可能被自动化信息源主导，因此建议使用 exclude。这些细节超出注释提供的信息，有助于代理正确预期结果。

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?

描述由三句简短句子组成，核心信息前置，随后给出使用建议和工具对比，没有冗余内容。每句都承担有用职责，结构高效。

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?

对于列表型只读工具，描述已包含核心目的、排序方式、与 get_rending 的区别、exclude 的用法及原因。schema 已覆盖 max 和 before 的细节，注释已覆盖安全特征，因此没有影响正确调用的重大遗漏。

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 已 100% 覆盖参数描述，因此基础得分为 3。描述额外解释了使用 exclude 的动机（高频率自动化信息源会主导结果），为参数提供了结构性背景，超越了 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?

明确说明该工具返回索引中所有节目的最新发布剧集，并按最新优先排序。它通过强调‘这是信息洪流，不是热门内容’与 get_trending 区分开，目的清晰且不会被误用。

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?

说明何时使用：获取最新发布内容时使用；并明确指出需要热门程度时应改用 get_current。还说明 exclude 过滤器值得使用，并解释原因为高频率自动化信息源会主导结果，这是明确的可操作指导。

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?

The annotations already declare readOnlyHint and destructiveHint as safe, so the description adds useful behavioral context: newest-activity-first ordering and the differentiation between updated feeds and new shows. This goes beyond what the schema and annotations convey, though it leaves exact recency windows unspecified.

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 concise sentences front-load the core behavior and ordering, then give the sibling distinction and usage guidance. Every sentence earns its place without redundancy or filler.

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

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

This is a simple, read-only list tool with fully documented optional parameters and safety annotations. The description tells the agent what the result means conceptually, how it is ordered, and when to use the main alternative. No critical call-invocation information 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 for all 5 parameters is 100%, so the schema carries the full parameter documentation burden and the baseline is 3. The description only loosely contextualizes 'published something recently' and adds no parameter-specific semantics 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?

The description states a specific action ('Feeds that published something recently, newest activity first') and explicitly distinguishes this tool from get_new_feeds by clarifying that it tracks updates rather than new shows. An agent can immediately tell which tool to use among the many feed-related 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 says 'Use get_new_feeds for shows that are new to the index', providing direct when-not/alternative guidance. It also explains the conceptual context of feeds vs shows, so an agent knows when this tool is relevant.

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?

With readOnlyHint and destructiveHint already covering the safety profile, the description adds meaningful behavioral context: the results are clipped by publishers, marked as the best moment, ordered as newest, and span the whole index. This goes beyond the annotations without contradicting them.

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-loads the core definition before the use-case sentence. The second sentence is slightly promotional and somewhat redundant, but it does add practical context about the feed's purpose. Each part has some value.

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 low-complexity read-only tool with one optional parameter and no output schema, the description tells the agent what it gets, why those items count as soundbites, and broadly how results are ordered. It stops short of describing exact output shape or pagination, but those are less critical here.

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 max parameter is fully documented in the input schema with range and default. The description does not add additional parameter context, but the schema already carries the burden adequately.

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 names a specific verb and resource (get newest soundbites) and establishes the key scope: across the whole index. It also explains which clips qualify, distinguishing it from per-podcast soundbite tools like get_soundbites.

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 gives clear use cases: a ready-made feed of podcasters' picks and a way to find shows using Podcasting 2.0 tags. It does not explicitly list when not to use it or name alternative tools, but the global scope and ready-made framing make the intended context clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it aggregates four underlying data sources into one call and measures cadence from real episode dates, which is important for interpreting results. It does not contradict any annotation and gives good detail about what behavior to expect.

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 sentences, all informative, with the core value proposition front-loaded first. The alternative-call comparison is concise and completes the routing guidance. No waste or repetition of schema details.

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 composite read-only tool with no output schema, the description does a strong job of enumerating the data it returns, so an agent kows what the response will contain. It could go further by describing the response shape or edge cases, but the combination of content list, usage guidance, and annotations makes the description effectively complete for invocation.

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

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

Schema description coverage is 100%, so both parameters are already well documented. The description reinforces that the episodes parameter feeds cadence and people analysis, but it does not add significant new meaning beyond the schema. Since the schema carries the full semantic weight, the baseline 3 is appropriate.

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

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

The description clearly states what the tool does: returns a complete profile of one show in a single call, enumerating metadata, cadence, episodes, credits, transcript/chapter presence, payment split, and crawler status. It also explicitly distinguishes itself from the sibling tools get_podcast, get_episodes, get_value_block, and check_feed_health, so an agent can select it 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?

The description gives explicit usage guidance: use this instead of making four separate calls, and treat it as the right first call when the question is about one show. This names both the alternatives and the condition that selects this tool, which is exactly what an agent needs to route correctly.

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?

The annotations already declare readonly, idempotent, and non-destructive behavior. The description adds useful context beyond those: the data comes straight from the episode record, there is no extra fetch, and the tags are optional and uncommon. No contradiction with annotations exists.

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 front-loads the core definition, then adds a rationale and source context. The three sentences are mostly purposeful, though the 'cheapest possible answer' phrasing is slightly embellished. Overall it is concise and well-structured.

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

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

For a simple one-parameter read tool with strong annotations and full schema coverage, the description is complete enough: it explains what the data is, why it matters, where it comes from, and its rarity. Without an output schema, a bit more exact structure would help, but the payload is adequately hinted.

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 only one parameter, episode_id, and the schema describes it fully as a Podcast Index episode id. The description adds no additional parameter-level meaning, but with 100% schema description coverage the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource as an episode's publisher-marked soundbites with start time and duration. The title plus first sentence make the purpose obvious. However, it does not explicitly distinguish this from the sibling get_recent_soundbites, so it lacks 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?

It gives concrete use cases: the cheapest highlight answer and a ready-made list for promotional clips. It also says it comes straight from the episode record with no extra fetch, which helps an agent decide when this is a cheap option. It does not explicitly state when not to use it or name an alternative tool.

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 mark the tool as readOnly, idempotent, and non-destructive, so the description only needs to add behavior beyond that. It adds significant value: format auto-detection (SRT, WebVTT, JSON, HTML), windowed reading with remaining/offset feedback, and the note that only JSON carries speaker names. No contradiction with 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?

Every sentence carries operational information: purpose, format handling, pagination behavior, the alternative tool, and the availability caveat. It is front-loaded with the core purpose and contains 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 read-only tool with three simple parameters and no output schema, the description explains the return format, how long transcripts are chunked, how to continue reading, and that transcripts are often unavailable. An agent has enough context to call it correctly and interpret 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 description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema for the format parameter, explaining that the default is the richest available format because JSON carries speaker labels, and it reinforces offset's role in windowed continuation. This pushes it above 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?

The description states a specific action ('Fetch and read the actual transcript'), the resource (an episode transcript), and the output shape (timestamped text with speaker labels). It also explicitly distinguishes itself from search_transcript, making it identifiable among many 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?

It gives clear when-to-use guidance: use this tool to read an entire transcript, and use search_transcript instead when looking for one specific moment because it is a single call rather than paging. It also warns that most episodes do not have transcripts, setting realistic expectations.

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

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

Annotations already cover read-only and non-destructive safety. The description adds meaningful behavior beyond annotations: it explains the semantics of the trending signal, the default time window, and how 'since' changes the read. This context is not available from annotations alone and helps the agent calibrate expectations.

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 three tight sentences with clear structure: purpose first, then usage context, then parameter guidance. Every sentence earns its place, and nothing is redundant or verbose.

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 a low-complexity tool, rich annotations, and a fully documented schema, the description provides the essential conceptual context that schema cannot: what 'trending' means, when to use it, and how to adjust parameters. No output schema is required to explain return values, and the description is sufficient for an agent to solicit and invoke 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 baseline is 3. The description adds usage-specific value by recommending filters (category, language) and explaining how 'since' widens the window for a slower, more stable read, which goes beyond the schema's raw descriptions. It does not cover every param, but the schema already does.

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 ('Shows') and resource ('trending in the index'), and clarifies it is a popularity signal rather than a chronological list. It distinguishes the tool from chronological list endpoints like get_recent_episodes and positions it for the 'what is hot in this category' use case.

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 declares when to use the tool: 'This is the tool for "what is hot in this category". It also gives when-not by noting it is 'rather than a chronological list', and provides actionable filter advice (category/language, widen 'since') for a better read.

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 destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: absent value blocks are reported as absence rather than errors, and value block presence only means the show can receive payments, not that it has. This meaningfully helps the agent interpret results.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and each following sentence earns its place by clarifying weight semantics, absence behavior, and interpretation. There is 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 single-parameter read-only lookup, the description covers the essential semantics: what the value block contains, how splits are expressed, how absence is represented, and how to interpret the block's meaning. It does not spell out an exact response structure, but there is no output schema and the description gives enough for correct invocation and result interpretation.

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 schema's 'show' parameter already explains accepted forms and auto-detection in detail. The tool description adds no parameter-specific information, so it does not need to compensate, but it also provides no extra value 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?

The description clearly identifies the resource and its purpose: the value-for-value block for a show, including listener payment wallets and weights. The title adds the verb 'Get,' making the operation clear. It does not explicitly distinguish this from the sibling get_episode_value, but the show-level scope is stated.

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

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

The description gives clear interpretive guidance: most shows have no value block, absence is reported plainly rather than as an error, and a value block does not imply payments were received. It does not name alternative tools or explicit when-not-to-use conditions, but the usage context and caveats are clear.

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

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

Annotations already communicate read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond that: categories have numeric ids, names and ids are both accepted elsewhere, and the naming is not Apple's genre list. This adds meaningful semantic context for an agent deciding whether to consume the result before category-based calls.

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, both purposeful. The first states exactly what is returned; the second explains when and why to call it. No filler or restatement of the title beyond what is useful.

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, no-output-schema enumeration tool, the description is complete: it tells the agent what the result contains (every category and its numeric id) and why the call is worthwhile. The lack of an output schema is mitigated because the first sentence effectively describes the return shape. Nothing essential 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?

The tool takes zero parameters, and the schema is empty, so the description cannot add parameter-level meaning. Per the baseline for a 0-parameter tool, a 4 is appropriate because there is nothing missing that the description needs to explain.

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: listing every category Podcast Index uses, with its numeric id. It also distinguishes itself from the sibling list/search tools by clarifying it is the universal category enumeration, and even differentiates its names from Apple's genre list. This leaves no ambiguity about what the tool returns.

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 explicitly tells the agent when to call this tool: once before filtering anything by category, because several other tools accept either the name or id and the names differ from Apple's genres. This is direct, actionable routing guidance with a clear rationale, even though there is no sibling category-specific alternative to exclude.

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, and destructiveHint=false. The description adds useful context beyond this: what qualifies as dead, that crawling was abandoned, and that entries may indicate duplicated feeds. It does not describe ordering or full return fields, but safety and mutability are well covered.

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 each sentence earns its place: definition, duplicate-feeds detail, use cases, and size caveat. It is front-loaded with the primary behavior before secondary details.

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?

The description gives enough to select and invoke the tool correctly: it is a large read-only list operation with one optional cap. Since there is no output schema, it could say a bit more about what fields each entry contains, but the duplicate-feed note partially fills that gap.

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

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

Schema description coverage is 100% and thoroughly documents the single `max` parameter, including default and local truncation. The tool description's 'This is a large list' reinforces that, but adds little semantic value 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?

The description clearly identifies the resource ('feeds Podcast Index has marked dead') and the action (list), and defines what 'dead' means operationally. This distinguishes it from siblings like get_recent_feeds and get_new_feeds.

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 concrete use cases: auditing shows that have quietly stopped and understanding directory churn. It does not explicitly name alternatives or when-not-to-use, but the 'dead' framing makes the intended context clear.

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

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

Annotations already cover the safe read-only, idempotent, non-destructive nature of the tool. The description adds useful behavior beyond that by disclosing that the list is paged and large, and by directing the agent to use start_at for paging.

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 two sentences with no filler. The first sentence states the resource and paging, and the second sentence explains why the tool matters and how to page, making every sentence purposeful.

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

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

For a simple read-only list tool with fully documented optional parameters and strong annotations, the description provides enough scope, purpose, and pagination guidance to invoke it correctly. There is no output schema, so a bit more detail about the response shape would be nice, but it is not essential for correct selection and invocation.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description in the schema. The tool description only reiterates the start_at paging behavior without adding new parameter semantics, so the schema carries the weight here.

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 opens with 'Every feed in the index carrying a value block, paged,' naming a specific verb and resource with a clear scope. It also positions the tool as the whole value-for-value list, distinguishing it from siblings like get_value_block or get_episode_value that target individual feeds or episodes.

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 gives clear usage context: it is useful for sizing the value-for-value space or finding shows that accept listener payments. It also instructs paging with start_at because the list is large, but it does not explicitly name alternatives or state when not to use this tool.

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 provide idempotentHint and openWorldHint, but the description adds concrete behavioral details: safe to call more than once, needs no API key, works on unconfigured installs, and will not add a feed. It goes beyond the annotations without contradicting them. It doesn't mention return values or rate limits, but those are less critical for a one-parameter ping.

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 focused sentences: action, when to use, safety/no-API-key constraints, and the explicit alternative. Every sentence earns its place, and the core action is front-loaded. No redundancy or filler.

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

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

For a simple tool with one parameter, no output schema, and supportive annotations, the description fully covers what an agent needs: purpose, trigger timing, idempotency, authentication requirements, and the edge case of non-indexed feeds. Nothing essential 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% and the show parameter is already well described ('feed id or its RSS feed URL', 'must already be in the index'). The description reinforces the 'already in index' constraint but adds no new format or syntax details, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Ping') and resource ('Podcast Index') with the purpose ('say a feed has changed'), and explicitly distinguishes itself from submit_feed. The title also communicates the exact use case, so an agent can tell this tool apart 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?

Provides an explicit trigger condition ('Use this straight after publishing an episode'), notes the fallback behavior ('the index will find it on its own eventually'), and names the alternative for a different scenario ('use submit_feed for that'). No inference is required.

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?

The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: it reads the Podcasting 2.0 person tag, matches names literally, has a known index-coverage limitation, and returns episodes rather than shows. This gives an agent accurate expectations about results and limitations.

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 front-loaded with the core function and stays compact across four sentences. Each sentence earns its place: behavior, use case, limitations, and result type. There is no wasted wording or redundant restating of the schema.

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

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

For a two-parameter read-only tool with no output schema, the description is complete enough to invoke correctly. It defines the input semantics, explains what results are returned (episodes, not shows), and exposes the two limitations that most affect whether the tool will return useful results.

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 adds extra semantic meaning for the q parameter by explaining that matching is literal and that inconsistent credits will appear under multiple spellings; max gets no additional description beyond its schema, but the parameter is self-explanatory.

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 names a specific verb and resource: find episodes where a named person is credited in any role. It also distinguishes itself from siblings by explaining it finds real Podcasting 2.0 person-tag credits rather than passing mentions, and by explicitly noting it returns episodes, not shows.

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 clearly frames when to use it: for guest research and tracing where someone has appeared. It also gives honest usage boundaries around person-tag coverage and exact-name matching, but it does not explicitly name alternative sibling tools or state when not to use it in favor of another tool.

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?

The annotations already cover read-only, idempotent, and non-destructive behavior, so the description's job is to add semantic context. It does this by explaining the Podcasting 2.0 medium separation and that results are feeds for albums/tracks rather than episodes, which helps set expectations beyond the structured fields.

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

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

Three sentences, front-loaded with the core purpose, and every sentence earns its place. The second sentence gives necessary domain context and the third gives actionable guidance without fluff.

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 search tool with no output schema, the description covers scope, result type (album/track feeds), and usage context. It could still add a brief note about response shape or pagination, but overall the agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents q, max, clean, and only_with_value. The description does not need to repeat parameter details, but it also does not add meaningful semantic insight about any specific parameter beyond what the schema provides.

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 opens with a specific verb and resource boundary: 'Search feeds whose medium is music rather than talk.' It also clarifies that these are albums and tracks, not episodes, which distinguishes it from the general podcast search tools in the sibling list.

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 says to use this for music discovery and warns that 'a normal podcast search will not surface them well.' This gives the agent a clear when-to-use signal and an implicit contrast with search_podcasts, the likely alternative.

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 idempotentHint=true, so no safety ambiguity exists. The description adds useful behavioral detail beyond the schema: it explains the matching model is keyword-based rather than semantic, and it reveals the return contract (feeds with Podcast Index feed id usable by every other tool). This is meaningful pragmatic 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?

Three sentences, each earning its place: what it searches, when to use it, and what the result looks like plus a caution about query style. It is front-loaded with the core action and scope, and there is no fluff or 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?

For a read-only search tool with a fully documented input schema, the description is complete. It explains the search scope, the result shape (feed id accepted by other tools), the general use case, and a key behavioral caveat about keyword matching. No output schema exists, but the description supplies the essential return contract.

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 parameter meaning is fully documented in structured form. The description reinforces that `q` matches title, author, and owner, matching the schema's wording, but adds no new syntax or semantic detail about the other parameters. The baseline of 3 is appropriate because the schema carries the parameter burden.

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 action ('Search the Podcast Index for shows by keyword') with explicit scope ('across title, author and owner'). It also differentiates from the sibling `search_podcasts_by_title` by presenting this as the general starting point rather than a title-specific lookup.

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 clearly tells an agent when to reach for this tool: when they have a topic or name and need to find a show. It also gives practical guidance on query formulation ('keyword-based rather than semantic... plain words work better than a sentence'). It doesn't explicitly name alternatives like `search_podcasts_by_title`, but the positioning as the general entry point makes the intended context clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it performs title-only matching, ignores author/owner, and is more precise for known names but weak for topic searches. This is useful qualitative behavior not evident from the schema alone.

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 sentences, front-loaded with the core scoping constraint, then the usage context, then a direct comparison to the sibling. Every sentence earns its place and there is no redundant repetition of schema or annotation 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?

The tool is a simple search operation with robust annotations and full schema coverage. The description fully covers what the tool does, when to use it, and how it compares to alternatives. No critical information is missing for an agent to select and invoke 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%, so the schema fully documents all four parameters. The description adds general context about title-only matching but does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Search shows by title alone') and explicitly distinguishes itself from search_podcasts by clarifying it ignores author and owner. It is immediately clear what this tool does and how it differs from its closest sibling.

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 gives concrete when-to-use guidance: use it when you know roughly what a show is called and a general search returned too many unrelated results. It also directly names search_podcasts as the alternative and characterizes when that sibling is better ('much worse for a topic').

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?

Beyond the read-only and idempotent annotations, the description discloses important behavioral traits: matching is literal and case-insensitive, results are not semantic, and an empty result means the exact words are absent rather than the topic was never discussed. It also clarifies there is no paging, which directly informs invocation expectations.

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 concise, front-loaded with the core purpose and return shape, then adds behavioral caveats. Each sentence provides distinct value: what it returns, why it is the fast path, how matching works, and how to interpret empty results.

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

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

For a simple three-parameter search tool with full schema coverage, the description covers return contents, matching semantics, result interpretation, and performance expectations. No output schema is present, but the described return shape—timestamp, speaker, surrounding conversation—is sufficient for an agent to invoke the tool and understand 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 description coverage is 100%, so the input schema already sufficiently documents episode_id, query, and max. The description adds useful search strategy context—such as trying multiple phrasings—but does not significantly expand parameter semantics beyond what the schema provides.

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 clear verb and resource: search inside an episode's transcript and return matching moments with timestamp, speaker, and surrounding conversation. It also differentiates this tool from siblings like get_transcript by framing it as the fast path for finding when something was said in one call without paging.

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 explicitly identifies the tool as the fast path for queries like 'when did they talk about X' and gives practical advice on how to search literal phrasing. It does not explicitly name alternative tools for cases where literal search is insufficient, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by naming the diagnostic facts it produces (credential status, clock offset, tool-group availability) and seuence as a first-line check. It is consistent with the annotations and does not need to repeat them.

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 dense sentences containing no wasted words: the first lists what is reported, the second gives the key usage scenario. The most actionable information is front-loaded.

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 zero-param diagnostic tool with no output schema, the description gives enough to decide when to invoke it and what it will verify. It could name the return format or fields, but that is not essential for tool selection and invocation in this simple case.

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 and schema description coverage is vacuously 100%. With no parameters to document, the description needs no extra parameter info, so the baseline 4 applies.

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

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

The description uses a concrete verb (Report) with three specific resources: Podcast Index credentials, clock skew, and available tool groups. This uniquely identifies a status/diagnostic tool and distinguishes it from every sibling search/get/submit tool.

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

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

Explicit usage guidance: 'Call this first when anything is failing in a way that looks like a permissions or connectivity problem.' It also tells the agent what to avoid ('rather than inferring the cause from an empty result'), giving clear when/why-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?

The description discloses critical behavior beyond what annotations already provide: writes to a public global directory read by many apps, has no removal path, returns existing id if already indexed, and fails cleanly without write permission. These details align with destructiveHint=true and idempotentHint=true, and add significant operational 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?

Four sentences, each carrying distinct, necessary information: core action, public/irreversible effect, idempotent behavior, and auth requirement. It is front-loaded with the main purpose and contains 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?

The description covers action, prerequisites, irreversibility, idempotency, and auth failure behavior. Without an output schema, it does not explicitly state what a successful new submission returns, though it implies an id is returned. This small gap prevents a perfect score.

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

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

Schema description coverage is 100%, with confirm, feed_url, and url all documented. The description repeats the confirm requirement and adds auth context but does not explain the url alias beyond what the schema already says, so it adds little beyond 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?

The description opens with a specific verb and resource: 'Add a podcast to Podcast Index by its RSS feed URL.' This clearly states what the tool does and implicitly distinguishes it from the sibling tool submit_feed_by_itunes_id, which uses a different input identifier.

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 gives clear usage context: it requires confirm: true, needs a separate write-permission API key, and is irreversible. It does not explicitly name alternatives like submit_feed_by_itunes_id or state when not to use this tool, but the context is strong enough for an agent to infer the appropriate scenario.

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?

The description goes beyond the annotations by disclosing that the feed is written to a public directory, that the action cannot be undone via this API, that confirm must be true, and that write permission is required. This gives the agent a concrete understanding of impact and preconditions.

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

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

Two sentences, with the primary purpose and distinguishing condition front-loaded, followed by a compact list of caveats. Every sentence contributes meaningful information with no 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 mutating tool with no output schema, the description covers the core operation, the required confirmation flag, permissions, irreversibility, and the public nature of the side effect. Nothing critical is missing for an agent to decide whether and how to invoke 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 schema already documents both parameters well. The description adds context that itunes_id is the id from Apple Podcasts and that confirm must be true, but it does not need to compensate for missing schema info.

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 action ('Add a podcast to Podcast Index') and the exact input mechanism ('using its iTunes id'), which clearly distinguishes it from RSS-based submission. The mention of 'for when you have an Apple Podcasts link but not the RSS URL' further clarifies the intended resource.

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 gives the use case: when you have an Apple Podcasts link but not the RSS URL. It also points to submit_feed as the related alternative and lists the shared caveats, giving the agent clear routing and prerequisite information.

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