PodLearn

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: an interactive clickable grid on MCP Apps hosts versus a markdown table elsewhere, which tells the agent what actually happens at call 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?

Three tight sentences, front-loaded with the picker purpose before the rendering detail. The final query sentence adds little since it duplicates the schema, but nothing is padded.

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 explains the return surface (clickable grid vs markdown table), which is the key thing an agent needs. It is only incomplete on the undocumented 'limit' parameter.

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 50%: 'query' is documented (and the description merely restates 'title/host filter'), while 'limit' (default 12, max 40) has no description anywhere and is never mentioned in the description. With low coverage the description should compensate but does not.

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 ('Open') and resource ('interactive episode picker') with the user-facing goal of picking an episode to read. It is distinguishable from siblings like list_episodes/search_episodes by its interactive-picker framing, but it never explicitly names or contrasts with those alternatives.

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 ('for the user to pick an episode to read'), and it usefully notes the host-dependent fallback. However, it gives no explicit when-to-use/when-not guidance and does not route the agent away from list_episodes or search_episodes for the same intent.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds value by disclosing credit consumption on first generation and caching behavior, which goes beyond annotations and informs the agent of side effects.

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

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

The description is two concise sentences, front-loading the main action and following up with prerequisites and cost behavior. Every sentence is informative with no redundancy.

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

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

The tool has low complexity (1 parameter, no output schema), yet the description covers purpose, prerequisites, cost, and caching behavior. It is fully adequate for an agent to correctly select and invoke the tool.

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

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

The schema has a single parameter 'episode_id' with UUID format, and schema description coverage is 0%. The description does not elaborate on the parameter beyond implying it's an episode ID. Given the simplicity, the baseline score of 3 is appropriate as the schema is sufficient but the description adds no extra semantic detail.

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

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

The description clearly states the tool generates a structured AI lesson from a completed transcription, specifying the output components (summary, key takeaways, sections). It effectively distinguishes from sibling tools like 'get_lesson_content' which retrieves existing lessons.

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

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

Explicit usage guidance: requires transcription_status 'completed' and explains credit consumption on first call with cached results on subsequent calls. This provides clear when-to-use and cost considerations.

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 are minimal (readOnlyHint=false, destructiveHint=false); description adds context about chaining and caller-scoped lookup for episode_id, but could specify whether it posts to LinkedIn directly or just generates text.

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 concise sentences, front-loaded purpose, but could be slightly more structured (e.g., separate lines or bullet points).

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 main usage and prerequisites; missing return value description but no output schema exists; adequate for a simple 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 0% schema description coverage, the description fully explains both parameters (lesson_id and episode_id), their types (uuid implied), and behavioral differences, compensating completely for the schema 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 clearly states it transforms an existing lesson into a LinkedIn post, specifies two ways to identify the lesson (lesson_id or episode_id), and distinguishes from generate_lesson by noting the prerequisite of an existing lesson.

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 states when to use (after generate_lesson) and explains parameter alternatives, but does not provide explicit when-not-to-use or alternatives (e.g., if you need to create a lesson first, use generate_lesson).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral insight by explaining the decision branching (whether transcription exists) and how the tool relates to downstream actions, which 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?

The description is two sentences, front-loaded with the main purpose and immediately useful decision logic. Every clause earns its place, with no redundant wording.

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 must hint at return content; it mentions 'full metadata' and two specific statuses, which is sufficient for a low-complexity read-only tool. It also covers related workflow steps, making the overall context complete enough.

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% for the single parameter episode_id, but the parameter is self-evident and the schema provides its UUID format. The description does not elaborate further, but given the trivial nature of the parameter, the minimal added explanation is acceptable.

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

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

The description clearly states the tool fetches full metadata for one episode and explicitly names two key fields (transcription_status and lesson_generation_status). It distinguishes from sibling tools by focusing on episode detail retrieval and readiness checks for transcription.

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

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

Provides explicit guidance on when to use this tool: to check if get_transcription is ready, and when not to, offering alternatives start_transcription and transcribe_url with parameter details. This directly addresses usage context and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context that the tool returns the caller's own stats and specifies 'transcribed/read' actions, which is useful behavioral detail beyond 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?

Single sentence, front-loaded with verb and resource, no wasted words. Every part contributes to understanding.

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 simple read tool with annotations, but lacks details on return format, pagination behavior, and what exactly the 'billing period' is. No output schema to compensate.

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 has limit and offset parameters with defaults and constraints, but description does not mention them or explain their purpose. With 0% schema description coverage, the description should compensate but fails to add any parameter meaning.

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

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

Description clearly states the tool retrieves episode-access usage stats for the caller, specifically counts of transcribed/read episodes in the billing period. This distinguishes it from sibling tools like get_episode_details or list_episodes.

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

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

Description implies usage for checking own usage but does not explicitly state when to use versus alternatives like get_user_credits or get_subscription_status. No exclusions or guidance on prerequisites.

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 and non-destructive. Description adds detail on content (title, summary, etc.) and confirms AI-generated origin. No contradictions.

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

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

Two efficient sentences with zero redundancy. Purpose and usage guideline 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?

Low complexity tool with one param and no output schema. Description covers return contents adequately. Could mention output format, but not essential.

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?

Single parameter lesson_id with schema (uuid) but no description coverage. Tool description adds no additional meaning or source guidance. Minimal value beyond 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?

Clear verb+resource ('Fetch the full body') with specific content list. Explicitly distinguishes from sibling generate_lesson.

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?

States when to use (retrieve prior synthesis) and when not (creating new, call generate_lesson). Provides clear alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns episode count and depends on local DB, which is useful beyond annotations.

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

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

Two sentences, no wasted words. Action verb first, then additional constraint. Excellent front-loading.

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

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

For a simple tool with one parameter and no output schema, description covers purpose, prerequisite, and expected return envelope. Could be more specific about 'full metadata' but sufficient.

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 has 100% coverage with description 'Local podcast id', but tool description adds context that the id must correspond to a local DB entry, reinforcing the prerequisite.

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 fetches full metadata for one podcast, including episode count, and distinguishes from search_podcasts by specifying the prerequisite of local DB. The verb 'Fetch' and resource 'full metadata' are specific.

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

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

Provides explicit prerequisite: podcast must be in local DB from search_podcasts. This guides when to use. No explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping detail that results are limited to the caller's own saved items, but says nothing about pagination behavior or result ordering.

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 zero filler; the resource and scope appear immediately. Nothing could be trimmed 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 simple read-only list tool with only two paginated parameters and no output schema, the description is close to complete, but it omits any paging guidance despite both parameters existing solely for that purpose. Adequate but with a clear gap for an agent iterating over results.

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

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

Schema description coverage is 0% for both limit and offset, and the description does not explain paging, defaults, or ordering at all. The description therefore adds no meaning beyond the bare parameter names, leaving the coverage gap unaddressed.

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

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

States a specific verb (List) and resource (the caller's saved/bookmarked episodes and lessons), which is enough to separate it from list_episodes and list_lessons. It does not explicitly name a sibling or state how it differs from the save/remove pair, but the resource is unambiguous.

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

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

The description gives no when-to-use guidance, no mention of pagination workflow, and no reference to save_item or remove_saved_item, which are the obvious adjacent tools. Usage is only inferable from the purpose statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds value by specifying the exact outputs (plan, status, period end). No contradiction.

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?

Single sentence with clear verb-resource structure, front-loaded with essential information. No unnecessary words.

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

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

Even without an output schema, the description lists all returned fields. For a simple, zero-param read tool, it provides complete context.

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?

No parameters exist. Baseline score of 4 for zero-param tools. Description correctly omits param details.

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

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

Description states verb 'Get' and resource 'subscription status' with specific outputs (plan, status, period end). No sibling tool overlaps, so it clearly distinguishes.

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. Usage is implied by the tool's purpose, but no alternatives or exclusions are mentioned.

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 indicate read-only and non-destructive behavior. The description adds transparency about pagination (max 120,000 chars, has_more pattern) and notes Claude's character cap. It does not mention error cases for incomplete episodes or response format, but the provided context is solid.

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

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

The description is compact and well-structured, with the purpose front-loaded, followed by pagination details and an alternative tool suggestion. Every sentence adds value without redundancy.

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

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

For a paginated tool, the description covers all critical aspects: what it fetches, pagination mechanics, character limits, and when to use alternatives. It lacks details on error handling or response structure, but given no output schema, this is sufficient for basic use.

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

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

The schema describes offset and max_chars with details, but episode_id lacks a description. The description adds contextual meaning to parameters through usage examples (e.g., using offset from prior page), but does not explicitly define each parameter. With 67% schema coverage, the description moderately supplements but does not fully compensate.

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

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

The description clearly states the tool fetches transcript text for a completed episode, using a specific verb and resource. It distinguishes itself from the sibling tool search_transcription, making its purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (full transcript retrieval) and when to prefer the alternative search_transcription (focused look-up). It also explains pagination handling with clear instructions on using offset for subsequent calls.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that segments carry timestamps; it says nothing about return size, pagination, or how many segments come back, which is meaningful for a transcript tool 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 the core action front-loaded and the usage hints trailing. Every clause earns its place, though the em-dash example list is slightly loose in structure.

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 fetch tool with annotations covering safety and no output schema, the definition supplies purpose and triggering intents adequately. The main remaining gap is that it doesn't connect the optional time-range parameters to the stated use cases like 'durations of specific parts'.

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 67%: start_time and end_time are documented in the schema as seconds, but episode_id carries no schema description and the description never mentions that start_time/end_time can narrow the segment window. Baseline 3 is appropriate since the schema does most of the work.

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 (Fetch) and resource (timestamped transcript segments), which is clear enough to distinguish from the sibling get_transcription, whose output presumably lacks timestamps. It stops short of naming that sibling explicitly, so the 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?

Gives concrete usage conditions with example intents ("jump to where they discuss X", chapter boundaries, durations of specific parts), which tells the agent when this tool is the right pick. It does not name get_transcription or search_transcription as the alternatives or state when NOT to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'remaining transcription credits' but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

Single sentence, no wasted words, front-loaded with action and resource.

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?

Given zero parameters, no output schema, and low complexity, the description sufficiently covers what the tool does. No additional context is needed.

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?

No parameters exist, so baseline is 4. The description adds value by specifying that the credits are 'remaining' and 'transcription', clarifying the type of credits.

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

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

Description clearly states verb 'Get', resource 'remaining transcription credits', and specifies 'caller's', distinguishing it from all sibling tools which deal with episodes, lessons, or other resources.

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 usage guidelines or alternatives are given, but since no other credit-related tool exists, the usage context is implied. A brief note on when to use it could improve clarity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that episodes are 'already in the local DB', reinforcing read-only nature. No contradictions. Sufficient transparency for a simple list operation.

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 main purpose, then usage notes and alternatives. Every sentence adds value with no redundancy.

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

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

No output schema, so description should explain return format or behavior. It mentions local DB but doesn't specify pagination, ordering, or response structure. Adequate but incomplete for a tool with 4 parameters.

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 25% (podcast_id described). The description adds context for podcast_id (requires it from search_podcasts), but does not explain limit, offset, or status parameters beyond schema defaults. Fails to compensate for low coverage.

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 lists episodes already in the local DB for a specific podcast. Distinguishes from related tools by mentioning cross-podcast search (search_episodes) and canonical listings (list_feed_episodes).

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

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

Explicitly states when to use: with podcast_id. Provides prerequisite (use search_podcasts first). Also states when not to use: for cross-podcast search or canonical listings, listing alternatives by 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 readOnlyHint=true, but the description adds valuable context: 'NO COST — pure discovery' clarifies it won't consume billing resources, and listing the enrichment fields (in_library, episode_id, transcription_status) sets expectations for what differs from the raw upstream data. No contradiction with annotations.

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

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

Each sentence earns its place: purpose, cost/discovery, enrichment details, and actionable transition to next steps. It is front-loaded with the primary action and remains tightly structured despite covering multiple aspects.

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?

Given no output schema, the description appropriately mentions the key returned fields and even explains downstream ingestion paths. Combined with good annotations and schema, this gives an agent everything it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 75%, so the baseline is 3. The description does not add new meanings for max, since, before, or feed_id, but it implicitly references feed_id when suggesting transcribe_url. The schema already documents these parameters well enough; the description's main value lies in usage flow, not param 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 opens with a specific verb+resource: 'Fetch the canonical episode list for a podcast directly from PodcastIndex'. It clearly distinguishes the tool from siblings like list_episodes (likely library-based) and browse_episodes by emphasizing upstream source and 'pure discovery'.

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 tells when to use the tool ('episodes you want to ingest') and provides concrete alternatives: call transcribe_url for new episodes or start_transcription for episodes already in_library. This is ideal usage guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the user-scoping constraint (only the calling user's lessons), but says nothing about pagination behavior, ordering, or how many items come back by default despite limit/offset parameters.

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 filler or repetition of the title. It is efficient, though its brevity is partly under-specification rather than discipline.

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 list tool with three parameters, no output schema, and only 33% schema coverage, the description leaves pagination semantics and result shape entirely unaddressed. The read-only annotations cover safety but not the missing call-time 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 description coverage is only 33% (episode_id alone is documented in the schema), so the description is expected to compensate for limit/offset and does not mention pagination at all. The only added meaning is the implicit user filter, which is not one of the three declared 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?

States a specific verb (List) and resource (saved AI-generated lessons) scoped to the calling user, which is enough to distinguish it from singular retrieval via get_lesson_content. It never names or contrasts a sibling tool, so it falls 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives. An agent is not told, for example, that generate_lesson creates lessons or that get_lesson_content fetches an individual one, so it must infer the boundary 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 indicate readOnlyHint=true and destructiveHint=false, so the description's behavioral disclosure is not critical. However, it adds the ordering behavior (most-recently-added first), which is helpful. No contradictory information.

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 concise sentences. The first conveys purpose, filter, and ordering. The second provides sibling guidance. Every word serves a purpose; no redundancy.

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

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

For a simple list-with-filter tool, the description covers the essential aspects: what it lists, optional filter, ordering, and sibling alternative. The schema already defines pagination parameters; extra description is unnecessary. The lack of an output schema is acceptable for a list endpoint.

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 33% of parameters have schema descriptions (only 'category' has a description). The description mentions 'optionally filtered by category', which adds context to that parameter, but provides no additional meaning for 'limit' or 'offset' beyond their schema definitions (type, default, bounds). With low schema coverage, the description should compensate more.

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

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

The description clearly states the verb 'List', the resource 'podcasts already in the PodLearn library', and key scope details: optional category filter and ordering by most-recently-added. It implicitly distinguishes from the sibling 'search_podcasts' which targets discovery beyond the library.

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 provides an alternative: 'For discovery beyond the library use search_podcasts.' This tells the agent when not to use this tool and directs to the correct sibling, leaving no ambiguity.

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

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

Annotations already provide destructiveHint: true, so the description's 'Permanently remove' reinforces that. It adds context that the action is limited to the caller's collection. No additional behavioral traits beyond annotations are disclosed.

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 consists of two short sentences that efficiently convey the tool's purpose and key context. Every word is meaningful, and there is no redundancy.

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

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

For a simple tool with one parameter, explicit destructive hint, and no output schema, the description covers all essential aspects: what it does, that it's permanent, and where to get the required ID. No additional information is needed.

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

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

The schema has 0% parameter description coverage. The description provides no details about the saved_item_id parameter beyond its source (get_saved_items). It does not explain its format, constraints, or how to obtain it.

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

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

The description clearly states the action (permanently remove) and the resource (saved/bookmarked episode or lesson). It distinguishes from siblings like save_item by specifying removal and from get_saved_items by indicating the source of the ID.

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 provides context on when to use the tool (to remove a saved item) and specifies that the saved_item_id comes from get_saved_items. It implicitly advises against using it for other purposes, but does not explicitly state alternatives or when not to use it.

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

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

Annotations already indicate this is not read-only and not destructive. The description adds that it's for the caller, but does not disclose other behaviors such as handling duplicate saves or permission requirements.

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 sentence of six words, containing zero wasted information. It is efficiently front-loaded.

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

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

For a simple save action, the description is adequate but lacks details on behavior when saving an already-saved item, response format, or error conditions. Given the presence of both 'save_item' and 'remove_saved_item' siblings, more context would be helpful.

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 50% (item_id has description, item_type lacks one). The description does not provide any additional meaning beyond the schema, failing to compensate for the missing item_type description.

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

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

The description clearly states the action (bookmark), the resources (episode or lesson), and the target (caller). It distinguishes from siblings like 'remove_saved_item' and 'get_saved_items'.

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 usage when bookmarking is needed, but provides no explicit guidance on when to use this tool versus alternatives like 'get_saved_items' to view bookmarks or 'search_episodes' to find content.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds the critical context that results are limited to local episodes only. No contradictions; the description consistently implies a safe read operation. Some additional context like rate limits or pagination behavior is missing but not essential.

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

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

Three sentences, each earning its place: first states purpose, second gives exclusion criteria, third clarifies status parameter. No redundant or vague language. Front-loaded with the most important information.

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

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

Given the absence of an output schema and the tool's moderate complexity (4 parameters, 1 required), the description provides enough context for an AI agent to understand the tool's role and when to use it. It could be improved by mentioning expected return format or pagination, but it is still sufficiently complete for selection and invocation.

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

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

Schema description coverage is only 25% (only query has a short description). The description adds meaning to the status parameter by explaining its filtering behavior. However, it does not provide additional semantics for query, limit, or offset beyond what the schema already provides (defaults, bounds). Since coverage is low, the description partially compensates but not fully.

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

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

The description clearly states it performs cross-podcast episode search by title/description and parent podcast name/author. It distinguishes itself from sibling tool list_feed_episodes by specifying it returns only local episodes, making the purpose specific and unambiguous.

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

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

Explicitly tells when to use this tool (searching local episodes) and when not (for podcasts not yet ingested, use list_feed_episodes). It also explains the status parameter filtering for transcribed vs untranscribed, providing clear usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. Description adds behavioral details: searches multiple sources, resolves URLs, and returns tagged rows. No contradiction.

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, no fluff, and the most critical information (what it does and when to use) is front-loaded. Every sentence adds value.

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

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

For a simple search tool with one parameter and no output schema, the description covers purpose, scope, behavior, and usage guidance comprehensively. No gaps given the tool's complexity.

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% with one parameter described as 'Search keywords or a podcast URL.' Description adds that it resolves Spotify/Apple Podcasts URLs and returns rows with source tags, augmenting the parameter's meaning 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?

Description clearly states it searches both PodLearn library and PodcastIndex by keyword, and resolves Spotify/Apple Podcasts URLs. It distinguishes from siblings like search_episodes and search_youtube by focusing on podcasts and being designated as the first move for identifying podcasts/hosts without IDs.

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 says 'First move when the user names a podcast/host but you don't have its id,' providing clear when-to-use guidance. Does not explicitly exclude other cases, but the context implies it's the starting point for podcast identification.

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?

Description adds that it returns matching chunks with surrounding context, which is beyond annotations (readOnlyHint=true). It implies no destructive effects and aligns with read-only nature. However, does not mention search limits or pagination.

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

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

Two sentences with zero redundancy. First sentence states purpose and output, second gives usage guidance. Every word earns its place.

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

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

For a simple search tool with 2 parameters and no output schema, the description adequately explains what it does, what it returns, and when to use it. No missing crucial information.

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 50% (query has description 'Topic, phrase, or speaker name'). Description clarifies that episode_id identifies a single episode and query performs keyword search, adding meaning to both parameters without repeating 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?

Clearly states verb 'keyword search' within resource 'single episode's transcript' and describes output 'matching chunks with surrounding context'. Distinguishes from siblings by specifying single-episode scope.

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 says 'Use instead of get_transcription when the user asked about a specific topic' and provides rationale: 'server does this faster + cheaper on context'. Clearly guides when to choose this tool over alternative.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds value by disclosing that 'Returns rows with a ready-to-transcribe url' and instructs to 'confirm cost and call transcribe_url(url, title)' for ingestion. No contradictions.

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

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

Three sentences front-load purpose and usage, provide output details, and next steps. No unnecessary words.

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 the core use case, output schema, and next action. Missing parameter details for 'max' but overall adequate for a simple search tool with 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?

Schema description coverage is 0%, and the description does not explain the 'max' parameter or add details beyond the schema. It only implies 'query' via 'by topic/keyword,' but fails to clarify the optional integer 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?

The description clearly states 'Discover YouTube videos by topic/keyword across all of YouTube,' specifying the action and resource. It distinguishes from siblings like search_podcasts and search_episodes by mentioning YouTube-first content.

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 tells when to use: 'when the user wants to learn from a talk/interview/lecture and has no URL — especially when search_podcasts / search_episodes find nothing.' Also notes 'NO COST: pure discovery.'

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses a key behavioral trait: 'COSTS 1 CREDIT (or subscription quota).' It also explains automatic inheritance of show, artwork, and feed linkage, which is useful context. It does not contradict the annotations.

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

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

The description is four sentences, front-loaded with the core purpose. Each sentence adds value, though the inheritance explanation could be slightly more compact. Overall it is appropriately sized for the tool's simplicity.

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?

Given the tool has only one parameter and no output schema, the description covers all necessary invoking context: prerequisites, exclusions, alternatives, cost, and automatic linkage. It is complete for an agent to select and invoke the tool correctly.

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

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

Although schema description coverage is 0%, the description compensates by clarifying that the episode_id must refer to an episode already in the library, and that no podcast context is needed. The schema already provides the format (uuid), so the meaning and constraints are sufficiently clear.

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

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

The description clearly states a specific action: 'Kick off transcription on an episode ALREADY in the library.' It highlights that the episode must already exist and distinguishes this tool from transcribe_url and transcribe_feed, which are for audio not yet in the library.

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

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

Explicit usage conditions are provided: 'Use only when the episode row exists and transcription_status is not "completed".' It also names the alternative for audio not in the library: 'For audio not yet in the library, use transcribe_url.' This gives clear when-to-use and when-not-to-use 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?

Discloses mutation (enqueue), cost (1 credit per episode), skip of already-transcribed episodes, return type (episode_ids), polling requirement. Annotations (readOnlyHint=false, destructiveHint=false) are consistent and description adds significant behavioral context.

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

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

Two well-structured sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Despite no output schema, description covers what is returned (episode_ids) and how to use them (poll). Includes prerequisites, cost, and behavior. Complete for a tool with 4 parameters.

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 covers 100% with descriptions. Description adds practical context: default max (10), cap (25), purpose of since/before (publish date filtering), and source of feed_id. More than baseline 3 due to added usage nuance.

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

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

Description clearly states it bulk-transcribes podcast episodes, specifies source (feed), and distinguishes from related tools like start_transcription (single episode) and transcribe_url (URL-based). Verb+resource+scope are specific.

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

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

Provides when to use (bulk feed transcription), prerequisites (feed_id from search/list tools), cost advice (confirm with user), and post-invocation steps (poll get_episode_details). Explicitly distinguishes from alternatives.

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?

Despite minimal annotations (readOnlyHint=false, destructiveHint=false), the description discloses key side effects: it creates a standalone episode row, consumes one credit/unit with an automatic refund on failure, returns episode_id, and notes asynchronous behavior with a polling instruction. This goes well 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?

The description is dense but every sentence earns its place: purpose, alternatives, cost/refund, association tips, return value, and async polling. It is front-loaded with the core purpose and structured logically, 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?

For a tool with 6 parameters, no output schema, and complex behavior (credit cost, async fallback, association with shows), the description covers all critical aspects: return type, polling method, and side effects. It is sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining why feed_id/podcast_name matter (to avoid 'External audio' and land under a real show) and references search tools for lookup. This enhances understanding beyond the schema's field-level descriptions.

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

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

The description clearly states the tool ingests and transcribes an external/arbitrary audio URL, using specific verbs and distinguishing from start_transcription (which handles existing episodes). It explicitly contrasts with the alternative for indexing-ready content, making its purpose unmistakable.

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 provides explicit guidance: use this for external URLs not in the index, but prefer start_transcription when an episode_id exists. It also advises passing feed_id/podcast_name from search tools to associate with a known show, giving concrete when-to-use context.

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