Podgist

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

Annotations only mark this as non-read-only, non-idempotent, non-open-world; the description adds the asynchronous job contract, the expected latency, the auth prerequisite, and the cost model. Repeated calls are implicitly non-idempotent because each call bills and spawns a job, which matches the annotation rather than contradicting it.

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 carrying distinct information: capability, polling contract, and cost/auth prerequisites. Front-loaded with the core purpose and zero 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 no output schema, the description correctly redirects to get_answer rather than promising a return shape, and it covers the async, auth, and billing context an agent needs. The only gap is the absence of any guidance on question phrasing or length limits, which matters at 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?

Only one parameter exists, so the description only needs light coverage, and the phrase 'drawn only from what was said on podcasts' does signal that the question must concern podcast content. However, schema coverage is 0%, so consumers get no hint about the 3–500 character bounds or that plain natural-language phrasing is expected.

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 (starts) and resource (a cited answer drawn only from podcast transcripts), which conveys both the domain restriction and the async-job nature. It doesn't explicitly contrast with the adjacent search_transcripts sibling, so an agent must infer that this is the answer-synthesis path rather than raw retrieval.

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 prescribes the follow-up workflow (call get_answer with the job_id until status is complete, usually under a minute) and points to list_services for billing/cost, plus notes an API key is required. What's missing is a negative case: it never says when to prefer search_transcripts or get_transcript instead of paying per question.

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 safety (readOnlyHint=true, openWorldHint=false), and the description adds substantive context beyond them: substring matching, most-transcribed-first ranking, a hard cap of 20 results, and no auth/key requirement with no cost. It omits matching case-sensitivity and whether truncated result sets can be paged.

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

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

Three short sentences, front-loaded with what the tool returns and why it matters, then cost/auth, then the result cap. Nothing is repeated from the schema or annotations.

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 work by naming the returned slug, the sort order, and the 20-result ceiling. Remaining gaps are minor: no statement on empty/no-match results or on how to retrieve more than 20 matches.

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 0%, so the description carries the burden, and it does explain that `name` is a substring match rather than an exact title. It does not address the schema's 2–100 length bounds or case sensitivity, but the core semantics are covered for a single required parameter.

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 the resource (public podcasts), the matching rule (name contains the text), and the ordering, so the agent knows exactly what it retrieves. It also implicitly separates itself from search_transcripts by pointing at that tool as the consumer of the slug. No ambiguity with any 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?

"with their slug (for the podcast filter of search_transcripts)" makes the intended workflow explicit: resolve a podcast here, then filter transcripts there. It does not state exclusions (e.g. when to skip this and query transcripts or ask_question directly), so it falls short of a full when/when-not rubric.

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 readOnlyHint=true and openWorldHint=false, the description adds two things the annotations cannot: the call must use the same API key that submitted the job (an auth constraint), and it is not billed (cost behavior not visible anywhere else). The 'status and, once complete, the answer' phrasing also discloses the asynchronous, poll-until-ready nature of the response.

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 with no filler. The return-value contract comes first, the auth prerequisite second, the cost note last — every clause carries distinct 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?

Absent an output schema, the description has to describe the payload, and it does so reasonably: status now, answer and cited passages later. It stops short of enumerating possible status values or telling the agent how to tell 'not ready' from 'failed', which is the one gap for a polling 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?

With schema description coverage at 0% for job_id, the description has to carry the load. It does add the key fact that job_id identifies a job created by ask_question, but says nothing about the format, length constraints, or how to obtain the id — it never names ask_question's output field.

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 (a job from ask_question) and enumerates what comes back: status, then the answer plus cited passages once complete. That is enough to tell it apart from the sibling ask_question, which creates the job. The verb is implied rather than stated (no 'retrieve'/'poll'), which keeps it just short of a 5.

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?

Mentioning that the job comes 'from ask_question' implies the intended sequence, and 'Needs the API key that asked' is a real prerequisite. There is no explicit polling guidance, no statement of what to do while status is incomplete, and no named alternative, so usage is implied rather than prescribed.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond them: per-account read scoping, an API key requirement, and per-call billing routed to list_services. For a paid authenticated fetch these are exactly the operational facts an agent needs.

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 tight clauses, front-loaded with what the tool returns, then the keying, then the access and cost constraints. 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?

Covers return shape, auth, billing, and access limits for a read-only tool with no output schema. The one gap is transcript length handling (truncation or size limits on long episodes), which matters for a bulk text payload.

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 0%, so the description must carry the burden, and it does: it maps the two params to podcast id (sid) and episode id (pid) and tells the agent where those values come from. It doesn't restate UUID format, but the schema's format field handles that.

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 (fetch one episode's transcript) with its return shape (speaker turns and timestamps) and its keying (podcast and episode id). The singular, one-episode scope cleanly distinguishes it from the plural sibling search_transcripts.

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?

Clarifies the provenance of the required identifiers ('the sid and pid of a search result'), implicitly routing the agent to search first and then fetch. It stops short of naming search_transcripts or ask_question as explicit alternatives or stating 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 declare readOnlyHint=true and openWorldHint=false. The description adds useful context beyond annotations: it requires an API key and is 'Not billed,' and it specifies the 30-day lookback window. It does not cover rate limits or error 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 description is front-loaded with the returned data, followed by compact auth and billing notes. Every clause earns its place with no wasted text.

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 read-only tool with no output schema, the description names the returned fields (balance, allowance, daily calls/cost), the 30-day window, and the auth/cost caveats. Nothing essential for 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?

There are zero parameters, so there is no parameter semantics burden. The schema is empty and fully described, and the description appropriately focuses on what data is returned rather than parameters.

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?

Clearly states it returns the key's account balance, monthly allowance, and daily calls/cost over the last 30 days. Lacks an explicit action verb, but the resource and data returned are specific enough that an agent can tell what it does.

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?

No explicit when-to-use or when-not-to-use guidance is given. 'Needs an API key' is a prerequisite rather than a usage rule, so the intended use case is only implied by the purpose.

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 openWorldHint=false, so the description isn't on the hook for the safety profile. It still adds genuinely useful operational context the annotations don't carry: the call is free and requires no API key. It stops short of describing result shape or whether the catalog changes over time.

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 clauses, front-loaded with the resource and its returned attributes, and the cost/auth note is packed tightly. Minor deduction for the slightly ambiguous "the tools, which need an API key," resolved only by the following 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?

With no parameters, no output schema, and simple annotations, the description covers the essentials: what is enumerated, that it includes key requirements and per-call pricing, and that calling it is free. Slightly thin on result structure, which matters more given there is no output schema.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. No misleading parameter hints are introduced.

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 (Lists) and a concrete resource (the tools/services Podgist offers) plus the two attributes returned (API key requirement and price per call). It doesn't explicitly contrast with siblings, but the discovery-catalog purpose is clearly distinct from ask_question/find_podcasts/get_transcript, so an agent can place it without opening a 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?

"Free; no key needed" tells the agent it can call this without credentials or cost, which implies it's a safe entry point for discovery, but it never states when to use this versus get_usage or the search/ask tools, nor any exclusion. Usage is inferred rather than instructed.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description earns credit for disclosing auth ('Needs an API key'), per-call cost ('billed per search'), result ordering ('newest relevance first'), and a 20-per-page result cap. These are traits an agent cannot get from structured fields. It stops short of covering failure modes, empty results, or rate limiting.

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 with no filler: purpose and return shape first, then filters, then the cost/auth caveat last. Every clause carries distinct 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?

With no output schema, the description correctly covers the return shape, ordering, and page size, which is what an agent needs before calling. It is slightly thin on how to paginate past the first page and has no mention of what happens on auth failure or zero matches.

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 20% — only 'podcast' is documented in-schema — so the description has to carry real weight. It adds the date format (YYYY-MM-DD), the scope of the podcast filter, and pagination behavior ('20 a page'), but never explains the required 'query' field's matching semantics or how 'page' interacts with the 20-per-page limit.

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 ('Full-text search across transcripts') plus the return shape ('matching episodes with snippets'), which clearly separates it from single-record tooling. It never names the sibling it contrasts with (get_transcript, ask_question), so differentiation is inferred 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 gives some routing signal via 'see list_services' for billing and frames the optional filters as narrowing scope. But it never says when to choose this over ask_question or get_transcript, and no exclusions or prerequisites are spelled out beyond needing an API key.

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