OndaCast

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=false), and the description adds real context on top: it creates the show's OndaCast page and is subject to per-client, per-day addition limits. What happens on a duplicate add is left to the idempotentHint=false annotation.

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 front-loaded sentences with zero filler: what it does, where the id comes from, the input constraint, then the quota. Each clause carries information the agent needs.

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?

Single required parameter fully documented in both schema and prose, output schema present so return values need no explanation, and rate-limit/mutation behavior disclosed. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, but the description still earns its place by clarifying a common failure mode: 'It takes no web address: only directory ids such as itunes-123 or pi-456', giving concrete id shapes beyond the regex in the schema.

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

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

States a specific verb and resource ('Add a podcast from a public podcast directory to OndaCast') and ties the input to the sibling that produces it. An agent can immediately tell this apart from the read-only search_* and get_* 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?

Explicitly names search_podcasts and the notOnOndaCastYet field as the source of valid ids, and flags this as 'the only tool that changes anything', which routes the agent correctly among siblings. It stops short of stating when-not-to-use cases (e.g. already-added shows, private feeds).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real value beyond that: figures are rounded DOWN and refreshed WEEKLY, and the response includes links to main pages — freshness and precision semantics an agent cannot get from 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?

One sentence, front-loaded with the verb and resource, and each clause (what it offers, catalogue size, rounding, refresh cadence, links) carries distinct information with no filler.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description still covers data precision, staleness and that links are included. Slightly more could be said about what 'what it offers' enumerates, but for a zero-parameter read tool this is close to complete.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate and it correctly implies a parameterless call.

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

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

Specific verb + resource: 'Get verifiable facts about OndaCast' with the scope spelled out as offering description plus catalogue size. It is clearly distinguishable from every sibling (search_*, get_charts, get_podcast), though it never names those alternatives explicitly.

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 implies the usage context (an agent wanting high-level figures about the service) but gives no explicit when-to-use/when-not guidance and does not tell the agent to prefer search_podcasts or get_charts for anything more granular.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context that the chart is derived from station plays and returns ranked entries with page links, but doesn't discuss freshness, caching, or empty-result behavior.

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

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

Two compact sentences that front-load the resource and scope, then the return shape. No filler.

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

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

With a full output schema and complete annotations, the description covers purpose, dimensions, and rough return shape sufficiently. It lacks explicit alternative guidance and edge-case behavior, but nothing critical for invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (kind, limit, window, country) are already documented in the schema, including enums and the country pattern. The description echoes the options but adds no syntax or format detail beyond the schema, so 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?

Specific verb ('Get') and resource ('live song or artist chart') with explicit scope dimensions (24h/7d, worldwide or country). The description makes clear this is a computed chart from station plays, which distinguishes it from siblings like get_station or radio_guide_now.

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?

Implies usage context ('counted from what stations played') but doesn't explicitly say when to choose this over radio_guide_now or get_station, nor state any exclusions. Usage is inferable from the resource name rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is settled. The description adds that latest episodes and page links come back, but says nothing about not-found or invalid-slug behavior, which is the main open behavioral question for a lookup tool.

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

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

One front-loaded sentence with no filler. The trailing enumeration of returned fields overlaps with the output schema, but it is compact enough not to bloat the definition.

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?

A one-parameter read tool with full schema coverage and an output schema needs little else; the description covers input forms and orients the agent to the returned shape. Only failure modes (missing podcast, malformed address) are left unaddressed.

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

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

Schema coverage is 100% and the single parameter's description already spells out both slug and full-URL forms. The description merely restates those accepted formats, adding no syntax or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Get one podcast from OndaCast') plus the identifier forms accepted, which clearly separates it from search_podcasts. It does not explicitly name the sibling it replaces, so a reader must infer the distinction rather than being told.

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

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

Usage is implied by 'by slug or OndaCast page address' — you call it when you already have a specific podcast identifier. There is no explicit statement of when to use this instead of search_podcasts, nor what to do if you only have a name.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds genuinely new behavioral context: stations that cannot play in a browser are excluded from availability, and the response links out to the station's OndaCast page for listening.

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?

Lookup keys and returned fields are front-loaded in the first sentence, and the availability caveat follows logically. Minor waste: the station's OndaCast page link is mentioned in the field list and again in the closing sentence.

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

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

An output schema exists, so the field enumeration is redundant but harmless; the description still carries the availability constraint that structured fields wouldn't express. Nothing essential for a correct call is missing apart from explicit sibling routing.

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 single parameter's description already gives both the slug form and the URL example. The description's "by slug or OndaCast page address" restates the schema without adding format, normalization, or error semantics (e.g. what happens on slug miss). Baseline 3 applies.

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

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

States a specific verb and resource ("Get one radio station from OndaCast") plus the two accepted lookup keys (slug or page address), and enumerates the returned fields. It doesn't name search_stations as the way to discover a slug, so the singular-vs-plural split with its sibling is left implicit rather than stated.

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

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

"It is for listening to or playing a station" implies the intended use case, and the note that non-browser-playable stations are unavailable hints at failure conditions. But there is no explicit when-to-use/when-not guidance and no routing to alternatives such as search_stations for finding a station first.

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 read-only, idempotent, non-destructive, and closed-world. The description adds genuine value on top: it discloses the returned payload (hosts, end time expressed in the show's own time zone, carrying stations, OndaCast page links) and the point-in-time constraint of "on air right now," which no annotation conveys.

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?

A single sentence that front-loads the action and scope, then enumerates the return payload, ending with the filters. No filler and no repetition of the title.

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

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

With an output schema present, return values need not be spelled out, and annotations cover safety; the description still goes further by flagging the time-zone nuance. Only minor gaps remain, such as the absence of any note on result limits or empty-result behavior.

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

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

Schema coverage is 100%, so the schema already documents genre, country (two-letter pattern), and limit. The description only restates that country and genre are optional filters and adds nothing about limit, defaults, or the maximum of 25; the 3 baseline 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?

Specific verb and resource: "List radio shows on air right now in OndaCast's radio guide." The real-time scope plus the mention of hosts, end times, and carrying stations makes it immediately distinguishable from podcast/audiobook/chart siblings, though it never names one explicitly.

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 closing sentence notes that country and genre are optional filters, which implies how to use the tool but gives no explicit when-to-use guidance, no exclusions, and no pointer to an alternative tool (e.g. search_stations) for different needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that the catalogue is public-domain only and that results come back with an OndaCast page link, but says nothing about ranking, partial-match behavior, or the 25-result ceiling.

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, front-loaded with the verb and resource; nothing is buried. The second sentence partially restates what the output schema already provides, a minor redundancy rather than a distraction.

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 full schema coverage, an explicit output schema, and annotations covering the safety profile, the description only needs to establish scope and selector semantics, which it does — public-domain-only catalogue, title/topic matching, optional language filter, and a page link returned.

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 are already documented. The description only echoes 'title or topic' for query and 'optional language filter', adding no clarification beyond the schema's own constraints (min/max length, limit bounds, language naming convention).

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

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

States a specific verb (search) and resource (public-domain audiobooks in the OndaCast catalogue) with scope qualifiers (title/topic, optional language). The resource noun implicitly separates it from search_podcasts and search_stations, but the description never explicitly contrasts with those siblings despite identical 'search_' naming.

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 implies when to use it (looking up an audiobook by title or topic, optionally narrowing by language) but gives no explicit when-not conditions and never names alternatives such as search_podcasts or catalog_facts for broader browsing. Behavior on empty or no-match queries is also unstated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value beyond that by disclosing result heterogeneity: results may include shows not yet on OndaCast from a public directory, which explains surprising or inconsistent names — a non-obvious trait an agent must know before trusting 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?

Three sentences, front-loaded with the core action and scope, then return size, then the non-obvious fallback. No filler and nothing repeated from 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?

Output schema exists, so return values need not be enumerated, yet the description still summarizes the shape (up to `limit` shows with an OndaCast page link). Combined with the fallback disclosure and the pointer to add_podcast, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema with defaults, bounds and maxLength. The description only restates that language is optional and that results are capped at `limit`, adding no syntax, format or value guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Search), a specific resource (podcasts), and the scope (the OndaCast catalogue, by title or topic). The medium noun 'podcasts' alone separates it from search_audiobooks and search_stations, so an agent can route without opening schemas.

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

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

Clearly signals context: search here for catalogue shows, with an optional language filter, and explicitly routes to add_podcast when a show appears from the public directory but isn't in OndaCast yet. It lacks an explicit 'do not use this for audiobooks/stations' exclusion, but the resource noun makes that near-unambiguous.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description's burden is lighter. It adds genuinely non-obvious context: only stations that play in a browser over a secure connection are listed, results cap at `limit`, and filter values must match OndaCast's English display names.

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

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

Front-loaded with the core purpose and sized well at four sentences. The only waste is the OndaCast page link being mentioned twice (once in the return summary, once in the 'for finding a station' sentence), a minor redundancy rather than a structural problem.

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

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

With an output schema present and full annotation coverage, the description need not explain return shapes. It supplies the result-set restriction, filter conventions and intended use, leaving only minor gaps such as result ordering and no explicit handoff to get_station for details.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by establishing a cross-parameter convention — country, genre and language all use the English names shown in OndaCast's filters — which the schema only partially states (it never says genre must be an English display name). It adds no guidance on query matching semantics, but the schema covers the constraints.

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 opening sentence names a specific verb (search), resource (live radio stations), catalogue (OndaCast) and the optional narrowing filters, so an agent can immediately tell this apart from get_station, get_charts or radio_guide_now. The scope sentence ('for finding a station to listen to or play') further pins down intent.

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

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

It states the use case clearly ('finding a station to listen to or play') and the follow-up action (each result links to the station's page). It never explicitly says when NOT to use it or names a sibling such as get_station for station detail, so it stops short of full routing guidance.

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