ATC, All Things Crypto

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

With annotations already covering read-only and idempotent behavior, the description adds useful context beyond annotations: it says results come from the ATC leaderboard, include caller/timestamp/direction/result, and are ordered newest first. It does not mention pagination or limit behavior, which keeps it from a 5.

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 a single tightly packed sentence with no wasted text, and the most important information — what the tool returns and ordering — 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?

The description covers return fields and ordering despite there being no output schema, which is helpful. However, it omits the date-range filtering behavior and limit semantics, leaving meaningful gaps for a tool with four parameters and low schema description 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 only 25%, with only the required asset parameter documented. The description does not explain the from/to date parameters or the limit parameter, so it fails to compensate for the schema 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 states a specific resource and query: callers of an asset on ATC, including timestamp, direction, and result. It is clear what the tool returns, but it does not explicitly distinguish itself from sibling tools such as speaker_calls or calls_leaderboard.

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 basic use case (calls involving an asset), but it gives no explicit guidance on when to choose this tool over siblings like speaker_calls or calls_leaderboard, and no exclusions or prerequisites are 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 cover read-only and idempotent safety, and the description adds genuinely new behavioral detail: the 20-scored-call eligibility threshold, hit-rate ordering, tie-breaking by total hits, and that ineligible speakers are listed separately. This is useful context beyond the annotations. It lacks detail on pagination or return format, keeping it from a 5.

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 dense sentence that front-loads the leaderboard identity and the ranking rule with no filler. It is efficient, though the ranking clause is compact enough that an agent may need to parse carefully.

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, no-output-schema retrieval tool, the description covers the ranking logic, eligibility rule, and separate-group behavior, which is what an agent needs to interpret results. The main gap is the undocumented limit parameter, but overall it is nearly 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?

There is one parameter (limit) with 0% schema description coverage, and the description never mentions it, its default of 10, or its max of 20. With coverage below 50%, the description should compensate but does not, leaving the parameter's semantics undocumented anywhere except the raw type/default/maximum.

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 the specific resource (ATC calls leaderboard) and the exact ranking rule (min 20 scored calls, ranked by hit rate, ties by total hits). It clearly distinguishes itself from siblings like speaker_calls or asset_calls by describing the aggregate leaderboard output. It stops just short of a 5 because it never explicitly states the returned shape (ranked list plus separate group of under-threshold speakers).

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

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

Usage is implied by the nature of a leaderboard, but there is no explicit when-to-use guidance or naming of an alternative such as speaker_profile for a single speaker's stats. The agent can infer it belongs to aggregate rankings but must reason about when to prefer it over per-speaker 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavior beyond that: the response shape is mode-dependent (summary + transcript excerpt for a segment vs. summary + chapters + segment ids for an episode), which an agent needs in order to plan a follow-up call.

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 the two modes clearly separated by 'or'. The parenthetical lists are dense but every element earns its place; only the missing sibling differentiation keeps it from a 5.

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 and full annotations, the description needn't explain return values, and it covers the dual-mode input adequately. The notable hole is that a sibling named get_episode exists with apparent overlap, and the description never explains the split — an agent choosing between the two has to guess.

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 lists the three accepted id forms, so the baseline is 3. The description goes further by mapping each input form to its output mode (id → segment, Space id/date → episode), which is meaning the schema does not carry.

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

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

States a concrete verb (read) and two resource modes: a show segment keyed by id, and an episode keyed by Space id or date, plus the payload each returns. The generic tool name 'fetch' is rescued by this detail. What it does not do is distinguish itself from the sibling get_episode, which appears to cover overlapping territory.

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?

'id from search' and 'segment ids to fetch' sketch a two-step workflow (search, then fetch), which is genuinely useful routing. But there is no explicit statement of when to pick fetch over get_episode or search_segments, and no exclusions, so selection between the closely related siblings is left 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value by enumerating the return payload: summary, speakers, tags, timestamped chapters and links — useful since there is no output schema. It omits error behavior for unknown dates/ids, which keeps it below 5.

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, both input forms, and the returned sections with zero filler. Nothing could be removed without losing 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 one-parameter read tool with full annotation coverage and no output schema, the description covers selection keys and return contents adequately. It lacks failure/not-found semantics and the 'ATC' acronym is unexplained, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% and the schema property already documents 'Show date like 2026-10-22, or X Space id'. The description's 'YYYY-MM-DD or Space id' merely restates that, adding no format edge cases or fallback behavior, 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 resource ('One ATC show') and both lookup keys (date or Space id), plus the payload returned. The word 'One' contrasts with the sibling list_episodes, though the sibling is never named explicitly, so differentiation is implied 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?

The singular 'One ... show' weakly signals this is the single-item lookup versus list_episodes/search, but no when-to-use guidance, prerequisites, or named alternatives appear. An agent must infer the routing from the sibling names 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context — result ordering (newest first) and the nature of the filters — but says nothing about pagination behavior or result size despite a limit parameter existing.

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 covering verb, resource, ordering, and filters with zero filler. Tag examples earn their place by clarifying filter granularity.

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

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

For a 5-parameter, zero-schema-coverage, no-output-schema list tool, the description should at minimum address the limit/pagination parameter and hint at the result shape. It covers filtering well but leaves the collection-size dimension 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 description coverage is 0%, so the description carries the burden; it explains from/to as a date range and gives concrete tag examples ('btc', 'stablecoins', 'nfts'), which is genuinely helpful. However, it omits the limit parameter (default 20, max 100) entirely, leaving one of five parameters undocumented anywhere.

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 ('List ATC shows') with ordering ('newest first') and the filterable dimensions, which is more than a tautology. It does not explicitly distinguish itself from siblings like search or get_episode, but 'List' vs. single-item/free-text search makes the intent reasonably clear.

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 word 'optionally filtered' implies how to narrow results, but there is no guidance on when to prefer this over search, search_transcripts, or topic_timeline, nor any exclusions. 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context: what the results look like (id, title, url) and that fetch is the follow-up for summaries and transcript excerpts, which shapes the agent's workflow.

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: the first defines the operation, the second defines the output and the follow-up path. Nothing is wasted and the most important information leads.

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 rich annotations and an output schema, the description need not explain return values, yet it still names the key fields and the fetch handoff, making it self-sufficient for invocation. The one shortfall is that it never positions itself against search_segments or search_transcripts, leaving sibling selection ambiguous.

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

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

Schema coverage is 100% and there is a single required 'query' parameter with an example, so the schema does the heavy lifting. The description broadens the semantic space to 'topic, project, person or claim', which is mildly useful, but adds no syntax, matching, or formatting guidance 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 with scope: 'Search every ATC show for a topic, project, person or claim', plus the return type. However, it does not differentiate itself from close siblings like search_segments, search_transcripts, or topic_timeline, which an agent must still guess between.

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 usage context (find shows/segments about a topic, project, person, or claim) and an explicit next step: 'Use fetch with an id for the summary and a transcript excerpt.' It lacks any when-not guidance or comparison to the sibling search tools, which is the main remaining gap.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by saying results are ranked by relevance and by naming the returned fields, though it omits pagination and limit 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?

The definition is a single front-loaded sentence with no filler. It efficiently packs purpose, result shape, and filtering into one compact statement.

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, it is valuable that the description names the returned fields and relevance ranking so the agent knows the result shape. The remaining gaps are around limit/pagination behavior and sibling differentiation, but the core information needed to invoke the tool is present.

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 60%: from, to, and speaker already have schema descriptions, while query and limit do not. The description's 'Filter by date range or speaker' reinforces existing schema information but adds no semantic detail for the required query or the limit maximum.

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 ('Find') and clearly identifies the resource as 'moments in ATC shows where a subject was discussed,' then lists the returned fields. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as search_transcripts or 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 mentions filtering by date range or speaker, but that is parameter behavior rather than guidance on when to choose this tool over alternatives. It gives no when-to-use, when-not-to-use, or sibling comparison guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine value by describing the return payload (quote text, speaker, X handle, timestamp, surrounding lines, episode link), which matters since there is no output schema. It omits pagination/limit 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?

Three short sentences, each load-bearing: scope first, return payload second, best-use case third. No filler or 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?

Purpose and return shape are adequately covered without an output schema, and annotations handle safety. However, the description never explains the date-range or speaker filters, so an agent cannot confidently use the tool's filtering capability from the description alone.

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 only 20%: only query is documented in-schema, and the description adds nothing about from/to date bounds, the speaker filter, or the limit cap of 20. With four of five parameters undocumented, 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?

States a specific verb and resource ('exact-word search across every ATC transcript line') and adds the intended use case ('who said X' and quotes). It does not explicitly distinguish itself from siblings like search or search_segments, so an agent must infer the boundary from the 'exact words' vs. semantic framing.

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?

'Best for who said X and quotes' gives an implied usage context, but there is no explicit when-not-to-use and no named alternative (search_segments, search). The agent must guess that broader/topical queries belong elsewhere.

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 covered. The description adds that the payload is show-level informational content rather than episode data, but says nothing about whether it is static/cached or how the result is shaped.

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?

It is a single short fragment with no wasted words, but the missing verb makes it read as a noun phrase rather than a tool definition. It is terse without being front-loaded on the action.

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-parameter, no-output-schema read of static metadata, enumerating the covered topics is close to sufficient — an agent knows what facts it will get back. Only the return shape and the meaning of 'ATC' remain unexplained.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the empty schema is self-explanatory. 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 enumerates what information is available (live schedule, hosts, panel, guesting, archive coverage) but never states the action — no verb like 'returns' or 'get show metadata'. It does implicitly distinguish this from the content-retrieval siblings (search, get_episode, transcripts), since this is the only static show-level metadata tool, but 'ATC' is an unexplained acronym.

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 list_episodes or search. The topic list hints at static show metadata, but no exclusion or alternative is named, so the agent must infer when this beats the 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is ordering ('newest first') and the enumerated result fields, which is useful given no output schema. It omits practical behavior such as the hard 20-item cap, what an empty result means, and how pagination/large result sets behave.

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 return shape; the field enumeration earns its space because there is no output schema. Slightly list-heavy but no filler or 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?

Covers what the tool returns and its ordering, which is the main gap for a read-only list tool, but with five parameters at 20% schema coverage it should explain the date-range and asset filters and the limit cap in order to be callable with confidence. Adequate but incomplete.

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 20% — only 'speaker' is documented in the schema (and even that format example is in the schema, not the description). The description says nothing about the to/from date window, the asset filter, or the limit ceiling of 20, so the four undocumented parameters are left entirely unexplained.

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?

Names a specific resource (a speaker's on-air ATC calls) plus the record it returns and the sort order, so an agent can distinguish it from asset-scoped or leaderboard siblings. It never names the alternatives (asset_calls, calls_leaderboard) explicitly, so differentiation is by inference rather than statement.

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, when-not-to-use, or alternative-tool guidance; the closest signal is 'Results come from the ATC leaderboard,' which hints at a related source but doesn't route the agent between speaker_calls, asset_calls and calls_leaderboard. Usage is only implied by the described scope.

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 needs no restating. The description adds real value by disclosing the shape of the response (aggregated appearances, first/last show, top topics, recent segments) in the absence of an output schema. It says nothing about behavior when the speaker is unknown, handle-format handling, or result size/cost.

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 subject and then a colon-delimited list of what the caller gets. No preamble, no redundant restatement 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?

For a one-parameter, read-only lookup with no output schema, the description supplies the essential return-content detail an agent needs to decide whether to call it. Missing only edge-case behavior (unknown speaker, ambiguous matches), which keeps it from a 5.

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 parameter already documents the name-or-handle form with concrete examples. The description's 'by name or X handle' echoes that, which is mild reinforcement rather than added meaning. Baseline 3 applies when the schema carries the semantics.

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 the resource (an ATC speaker, identified by name or X handle) and enumerates what the profile contains: appearances, first and last show, top topics, recent segments. That is specific enough to distinguish an aggregated profile from a plain listing. It stops short of naming the closest sibling, speaker_calls, which plausibly returns a call list rather than a profile, so an agent must infer the split.

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

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

Usage is implied by the content list: reach for this when you want an overview of a speaker rather than a transcript search. There is no explicit when-to-use statement, no exclusions, and no mention of speaker_calls or search_segments as alternatives for narrower questions.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is additive — and it does add the ordering guarantee ('oldest first') and the shape of each returned item, neither of which is in the annotations. It stops short of disclosing truncation behavior, which matters given the limit cap.

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, both earning their place: the first defines the output and ordering, the second gives the question shape it serves. Front-loaded and free of 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?

Adequate for a lookup tool: return contents and ordering are described, safety is carried by annotations, and there is no output schema to explain. The remaining gap is behavioral completeness around the limit cap — an agent asking about a long-running topic has no idea whether results are silently truncated.

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 only 25% — just `topic` carries a description and examples. `from`, `to` and `limit` are inferable from their types, patterns and bounds, but the description supplies zero additional semantics: not whether the date bounds are inclusive, whether they are required for a timeline to be meaningful, or what happens when a topic exceeds the 60-segment ceiling.

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 pairing: it returns every matching segment for a topic in chronological order, and it spells out the payload ('what was said, who said it and links'). What's missing is sibling differentiation — search_segments and search_transcripts in the same family could plausibly be reached for the same query, and the description never separates 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?

One concrete use case is offered ('how has the show's view on X changed'), which implies the tool is for evolution-over-time questions rather than one-off lookups. However, there are no exclusions and no named alternatives, so an agent has no stated rule for choosing this over search_segments or search when both seem applicable.

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