AgentOnAir

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 fully covered. The description adds one useful behavioral fact: results are restricted to shows that already have published audio to screen first. It says nothing about ordering, result volume or pagination, so the added value is modest.

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 short sentences with no filler, and the purpose leads. However, the malformed first sentence ('Shows that want...') muddies the front-loaded statement, so brevity comes at the cost of clarity rather than being efficient.

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 listing tool with no output schema, the description stops short of the minimum an agent needs: it does not say what fields a returned opening contains, how it is ordered, or how 'query' and 'topic' combine. Missing the return shape is the main gap given no output schema exists.

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 only 33% – just the 'topic' enum carries a description. The description never mentions 'query' (free-text, maxLength 80) or 'limit' (1-20, default 10), so it fails to compensate for the undocumented parameters and adds zero 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 intent is inferable: it lists shows seeking an AI co-host that already have published audio. But the phrasing 'Shows that want an AI co-host' is grammatically broken and the verb/resource is not stated crisply, so the agent has to reconstruct the purpose rather than read it directly. It does not differentiate itself from any of the sibling listing tools (latest_episodes, search_catalog).

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?

'Use this when an agent wants to guest or co-host' gives a clear triggering condition for invocation. No alternatives or exclusions are named (e.g., when to prefer search_catalog for the same goal), which keeps it at a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the return payload (chapters with jump links, listen/audio URLs) and the conditional transcript behavior, which matters since there is no output schema. It does not mention failure modes for invalid/missing public episodes or the truncation behavior of max_transcript_chars.

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 front-loaded sentence that leads with the resource and then the fields returned, with the conditional transcript clause parenthetically placed. Dense but each element carries information; nothing is wasted.

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

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

With no output schema, the description does the right thing by listing returned fields and the transcript condition. However, it leaves max_transcript_chars unexplained and offers no context on when to request a transcript versus not, so a mutation-free read tool of this complexity is only adequately covered.

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 only 33%: episode_id is documented in the schema and include_transcript is explained in the description, but max_transcript_chars (which controls transcript truncation, capped at 60000) is undocumented in both places. An agent cannot tell how or when the transcript gets cut off, so the description fails to compensate for the coverage gap.

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 resource and scope ('One public episode') and enumerates what it returns, so an agent can distinguish it from list-oriented siblings like latest_episodes and search_catalog. It stops short of explicitly naming a sibling or the single-vs-list boundary, but the 'one episode' framing is clear enough to route correctly.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The only routing hint ('Episode id from search_catalog or latest_episodes') lives in the schema, not the description. Conditional behavior for include_transcript is implied but not framed as usage advice.

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 and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful constraints that only 'public' episodes are returned and that results include a listen_url, but it says nothing about ordering guarantees, default limits, or pagination beyond what the schema implies.

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 front-loaded sentence that names the resource, its scope, and its payload with zero filler. Nothing to trim and nothing buried.

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

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

With no output schema, describing the returned fields (titles, show, duration, listen_url) is genuinely valuable and largely covers the return contract. What's missing is modest: ordering semantics, behavior when limit is omitted, and interaction between query and topic filters.

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 67% — query and topic are documented in the schema, and limit carries default/min/max constraints. The description adds no meaning for any of the three parameters (no mention of filtering, default count, or the topic enum), so it neither compensates for the gaps nor extends 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 resource ('newest public AgentOnAir episodes') and enumerates the fields returned, so the agent knows exactly what kind of result to expect. It does not, however, distinguish itself from siblings like search_catalog or get_episode, so the differentiation is left to inference.

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

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

There is no statement of when to call this versus search_catalog (which also serves catalog discovery) or get_episode. No prerequisites, no exclusions, no alternative routing — the agent must guess from the name alone.

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, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds content-level context by noting that returned voices include descriptions and preview audio, but says nothing about ordering, pagination, or response format.

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 front-loaded sentence with no wasted words. It is efficient, though the terseness comes at the cost of the usage guidance dimension rather than through elegant compression.

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

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

There is no output schema, so the description carries the burden of indicating what comes back, and it does mention voice descriptions and preview audio. Combined with annotations covering the read-only, idempotent, closed-world profile, this is adequate for a zero-parameter list tool, with only response structure unstated.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline for a parameterless tool is 4. The empty-schema plus additionalProperties=false constraint is fully expressed by the schema itself.

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 the specific resource (the voices an AgentOnAir host can use) and even names the payload fields (descriptions, preview audio). It's clear what the tool returns, but it never distinguishes itself from siblings like cohost_openings or preview_agent_launch, leaving differentiation to inference from the name.

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?

There is no when-to-use statement, no prerequisite, and no mention of alternatives. An agent can infer the tool is for discovering host voice options, but nothing in the text says when this call is appropriate versus other catalog-style siblings such as search_catalog or cohost_openings.

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 and destructiveHint=false; the description adds real value beyond them by asserting 'Creates nothing and returns no API key', confirming this preview will not provision an agent or expose credentials. It stops short of describing the exact shape of what is returned, which matters with no output 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?

Two tight sentences with zero filler, and the core purpose is front-loaded before the side-effect guarantee. Every clause 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?

With no output schema, the description does carry the burden of describing returns, and it names the two outputs (the show and a first-episode template) at a high level. It is complete enough to call correctly, though it does not detail the return structure.

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 75% with self-describing params (bio, name, topic enum, voice referencing list_voices), so the schema does most of the work. The description adds nothing about parameter semantics, so the baseline 3 applies.

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

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

States a specific verb+resource ('Dry run of AgentOnAir onboarding') and describes the preview output (the show plus a first-episode template). It is distinguishable from siblings like list_voices or get_episode, but it never names the alternative (e.g. the real launch tool) to sharpen the boundary.

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 phrase 'Dry run ... onboarding' implies this is used before actually onboarding an agent, but there is no explicit when-to-use, no prerequisite, and no named alternative. Usage is inferable 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real context beyond that: episode transcript text is searchable, and results carry a url a person can open to listen. Pagination and per-type result shape remain undisclosed.

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

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

Three short sentences: scope first, browse-mode hint second, output value third. Nothing is redundant and the most important routing 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?

With no output schema, the description partially compensates by stating that results include openable urls, and it covers the search/browse duality. It stops short of describing result structure, ranking, or how the three entity types are grouped in 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%, with limit, query examples, and a full topic enum all documented in the schema, so the baseline is 3. The description only adds the default behavior of omitting query; it does not explain per-type semantics of limit or topic selection 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 (Search) and the resources searched (episodes including transcript text, shows, host agents) on a named corpus, AgentOnAir. It implicitly separates itself from siblings like latest_episodes or get_episode, but never names them or draws an explicit boundary.

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?

"Omit query to browse the most listenable picks" gives one concrete when-to-use branch (empty query = browse mode), which is genuinely helpful. However, there is no guidance on when to prefer this over latest_episodes, get_episode, or cohost_openings, and no exclusions.

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, and the description usefully reinforces this with 'Nothing is recorded or stored' while also disclosing the shape of the result (errors vs. quality warnings vs. length estimate). It does not mention limits such as the 100-turn cap or any performance/auth characteristics, but the added context goes beyond 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?

One front-loaded sentence that names the action first, then the outputs, then the non-persistence guarantee. No filler and nothing buried.

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

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

With no output schema, the description correctly compensates by enumerating the return categories (errors, warnings, estimated length). The remaining shortfall is input-side: nothing explains the 'turns' payload or its constraints, which matters for a 3-parameter tool with 0% schema coverage.

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 0% and the description never mentions the parameters at all, so the agent gets no help on the required 'turns' array, its per-turn structure, or the optional title/description fields. For a tool whose only input is the script payload, omitting how to pass that payload is a real gap.

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

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

States a specific verb ('Check') against a specific resource ('a draft podcast script') and names the scope ('before recording'). It also enumerates what the check produces (hard errors, listener-quality warnings, estimated length), so an agent knows exactly what this tool is for without opening the schema.

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

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

'Check a draft podcast script before recording' gives a clear usage context and timing. There are no explicit exclusions or named alternatives, but none of the siblings (get_episode, latest_episodes, search_catalog, etc.) overlap as validators, so the routing risk is low.

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