Storyflo

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

Annotations already declare readOnlyHint true, so non-destructive. Description adds rate limit behavior, which is beyond annotations. No contradictions. Good addition for a heavy 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?

Two sentences, front-loaded with action, no wasted words. Each sentence adds value (function, rate limit, usage prompt).

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 3-param, no-output-schema tool with 8 siblings, the description covers purpose, usage, and a key behavior (rate limit). No return format explanation, but acceptable for a digest tool. Sibling differentiation implicit.

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 0%, so description must compensate. It mentions 'top-N' (limit), 'selected verticals' (verticals), 'requested window' (window), linking parameters to purpose. However, does not detail constraints or formats beyond schema's own enums/range.

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 aggregates top-N articles across selected verticals for a requested window, using specific verb 'aggregate' and resource. It distinguishes from siblings like get_article (single article) and search_articles (search), making it clear for daily digest prompts.

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 use case ('read me today's tech news' style prompts) and warns about rate limit impact ('Heaviest action'). Lack of explicit when-not-to-use or alternatives, but sibling context helps.

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 convey read-only, safe, idempotent behavior. The description adds that the tool is public (no auth required) and explains the rolling window semantics (e.g., today ≈ 24h). No contradictions 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?

The description is extremely concise: three sentences that front-load the purpose, specify a use case, and explain key parameter details. 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 digest tool with 2 optional parameters and no output schema, the description covers the core functionality, typical usage, and safety. It lacks a brief note on the limit parameter's meaning (e.g., maximum number of cases returned), but overall is quite 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?

Schema description coverage is 0%, so the description must compensate. It explains the window parameter with options and default, but does not describe the limit parameter or its effect. Partial compensation but insufficient for full clarity.

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 returns the most-recently-published Declassified cases over a rolling window. It explicitly provides a use case ('what's new in Declassified this week') and distinguishes from sibling tools like search_declassified and get_declassified_case.

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 explicit context for when to use the tool ('what's new in Declassified this week') and explains the window options. While it does not explicitly list alternatives or when-not-to-use, the use case and context make it clear compared to siblings.

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, so the safety profile is clear. The description adds useful context about the return fields (body_text, audio_url). 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?

The description is a single sentence that is front-loaded and contains no unnecessary words. Every word 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 fetch tool with one parameter and no output schema, the description adequately covers the purpose and return fields. It could be slightly more detailed about the full return structure, but it is 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?

The parameter 'slug' is not described in detail beyond 'by slug', and schema description coverage is 0%. However, the parameter name is self-explanatory, and the description does add context that slug is the identifier for fetching.

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 (Fetch), the resource (full record for an article), the method (by slug), and what is included (body_text + audio_url). This distinguishes it from sibling tools like get_audio_url or search_articles.

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

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

The description implies when to use the tool (when you have a slug and want the full record), but it does not provide explicit guidance on when not to use it or mention alternative 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds tier-specific behavior (free vs plus/pro) and mentions 'playable' format, adding value 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. First sentence states purpose, second adds behavioral detail. Highly concise.

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 tool with annotations and one parameter. Missing details on error handling, URL format, or slug validation, but not severely 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?

With 0% schema description coverage, the description should explain the 'slug' parameter. It does not, leaving ambiguity about what a slug is or its format.

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 title and description clearly state the tool resolves a playable audio URL for an article. It distinguishes from siblings by being the only tool handling audio URLs.

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 use for retrieving audio, but does not explicitly state when to use or avoid it. No mention of alternatives like get_article which might provide audio links.

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, idempotentHint, destructiveHint. The description adds value by detailing fail-closed behavior, attribution-aware parameter, and clarifying it's an editorial linkout not a trading prompt, going 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 well-structured with clear sections and no wasted sentences, but contains some jargon like 'Markets-as-INPUT posture' that could be simplified. Still, it's efficient and 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?

Despite lacking an output schema, the description covers return value purpose, error cases (fail-closed), and behavioral traits. It provides complete context for a simple URL-returning tool.

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

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

Schema coverage is 100%. The description adds meaning beyond schema by explaining asset is case-insensitive and upper-cased, and embedder_slug defaults to 'storyflo', enhancing parameter understanding.

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 returns a Kraken affiliate URL for a given crypto asset, using specific verbs and resource. It distinguishes from sibling tools like get_market_linked_stories by focusing on generating a link rather than fetching stories.

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 'When to use' section tells to surface the link in show-notes or MCP-client renderings, and explicitly warns not to inline into spoken audio without proper framing. This provides clear context and exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds 'Public — no auth required' and specifies return of up to 5 related cases, adding valuable behavioral context 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, incredibly concise, front-loaded with action and resource, no redundant 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?

For a simple get-by-slug tool with complete schema coverage and thorough annotations, the description lists all return fields, no output schema needed. Complete and 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?

Input schema covers slug with 100% coverage and description adds that it comes from search_declassified. Adds helpful context beyond the schema, earning above baseline.

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 the action ('Fetch'), the resource ('full record'), the key identifier ('by slug'), and lists specific return fields. Distinguishes from sibling tools like search_declassified which returns a list.

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: 'Use after search_declassified when the agent needs the full case body to summarize, narrate, or hand off audio playback.' Provides clear context and excludes alternative uses.

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, so the safety profile is clear. The description adds significant value by explaining that this is original analysis computed by Storyflo (not market-data redistribution) and that it never returns raw external market odds. It also provides citation guidance, which is behavioral context 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 a single paragraph that front-loads the main purpose and includes all necessary details. While it is somewhat long (10+ sentences), every sentence adds value. It is not overly verbose but could be slightly more streamlined.

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, the description thoroughly enumerates each item's fields (divergence value, news-narrative probability, market descriptor, story links, market venue link). It also covers scope (ranking by absolute divergence), integrity (original analysis), and legal disclaimer (not investment advice). This makes the tool understandable without needing an 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 input schema has 100% description coverage and only two parameters (limit, source). The description mentions filtering by source and the limit parameter implicitly but does not add new meaning beyond what the schema provides. With perfect schema coverage, a score of 3 is appropriate per guidelines.

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 returns a specific computed metric (Storyflo Divergence Index) that measures disagreement between prediction markets and news narratives. The verb 'Get' combined with the specific resource name and detailed explanation distinguishes it from sibling tools, which are largely unrelated (e.g., get_article, search_articles).

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 indicates the tool is public, requires no auth, and is not investment advice. It also mentions filtering by source (kalshi|polymarket) and citing the original analysis. However, it does not explicitly state when to use this tool vs. alternatives among siblings, though the uniqueness of the computed index implies its specific use case.

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, openWorld, idempotent, and non-destructive. The description adds value by specifying the endpoint is public (no auth) and describing the manifest contents, going beyond annotation hints.

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 concise sentences cover purpose, usage, and auth. No wasted words; front-loaded with the core 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 simple one-parameter tool with no output schema, the description gives sufficient context: what it returns, when to use, and auth status. Could be slightly enhanced with response structure details, but overall 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?

Schema coverage is 100% with a clear slug description. The main description adds no new parameter info beyond the schema, so baseline of 3 is appropriate.

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 wraps the public /embed/<slug>/manifest.json endpoint and lists contents (creative formats, voice options, etc.). The title 'per-embedder agent manifest' distinguishes it from sibling get_embedder_network_manifest, and usage scenarios are given.

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: after register_embedder or when reading another partner's manifest to plan an ad buy. Also notes it's public with no auth, guiding safe invocation.

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 fully cover behavioral traits (readOnly, openWorld, idempotent, non-destructive). Description adds that it is public and no auth, consistent with annotations. 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 sentences, front-loaded with the endpoint and purpose. No wasted words. Efficient and clear.

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 parameterless, simple fetch tool with comprehensive annotations, the description fully explains the tool's purpose, contents, and usage context. No missing 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?

No parameters exist; schema coverage is 100%. Description indirectly explains what the tool returns, providing context that substitutes for parameter documentation. Baseline 4 is appropriate.

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 wraps the public /embed/network-manifest.json, listing specific contents (creative formats, payout rails, etc.), and distinguishes itself from sibling 'get_embedder_manifest' by being platform-wide.

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 describes when to use: evaluating wiring storyflo into a surface or when a DSP needs canonical integration shape. Also notes 'Public — no auth required.' Does not explicitly contrast with siblings, 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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral transparency beyond annotations: it clarifies that the tool returns qualitative signal tags and link-outs but never returns raw prices, probabilities, volumes, or open interest. This is valuable context not present in 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 front-loaded with the core purpose and is concise at five sentences. Every sentence adds useful information (what it does, what it returns, what it doesn't return, when to use, filter options). There is no wasted or redundant 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?

Given the tool has no output schema, the description adequately explains content (qualitative signal tags, link-out to Kalshi) and explicitly states what is NOT returned (market prices, probabilities, etc.). It covers the key aspects needed for an agent to understand the tool's output. However, it does not mention pagination or response format, which is a minor gap.

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 schema already documents most parameters. The description adds value by explaining the 'signal' parameter's enum values (e.g., high_velocity = market repricing meaningfully in last 24h, genuine_uncertainty = 40-60% band). For other parameters (limit, category, vertical), the description does not add beyond schema, but the overall param semantics benefit from this contextual explanation.

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 ('Get') and clearly identifies the resource ('stories with active matched event-contract markets'). It distinguishes from siblings by stating that the tool does not return market data (prices, probabilities) and is an editorial sourcing surface, which is a unique value proposition.

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 explicitly states when to use this tool ('when the agent needs to know which Storyflo stories are about news themes that have an actively traded event contract') and gives concrete examples (World Cup matches, political mention contracts). It also explains what NOT to do ('not market-data redistribution'). However, it does not directly mention alternatives among 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 mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical context: identity resolution from OAuth token and a zeroed shape for anonymous callers. This goes 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: first defines the output clearly, second gives three concrete use cases and one behavioral note. No redundant words, front-loaded with purpose.

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 names the fields returned. It also covers authentication and anonymous edge case. Could specify data types, but adequate for an agent to decide usage.

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 and 100% schema coverage. The description adds no parameter details because none exist, but it compensates by explaining the output fields. Baseline is appropriate.

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

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

The description states the exact resource (caller's trailing 30-day MCP tool-usage summary) and the specific data fields (total calls, success rate, p50 latency, per-tool counts). It distinctly differs from sibling tools, none of which provide usage stats.

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 explicitly lists use cases: self-budgeting against rate limits, auditing tool usage, deciding on paid tiers. It does not provide negative guidance or alternatives, but the sibling set lacks similar tools, making the context clear enough.

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 description discloses that the token is 'minted on first call and stable thereafter', aligning with the idempotentHint annotation. It adds context about URL privacy and credential usage 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?

The description is front-loaded with the purpose and is reasonably concise (5 sentences). It includes necessary warnings but could trim some redundancy (e.g., explanation of the model).

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 no output schema, the description explains the return value (a URL) and its use. It could specify the exact response format but suffices for the intended use case.

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 repeats the parameter purpose and adds the minting behavior, but adds minimal new semantics beyond the schema's own 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 tool returns 'the caller's PRIVATE per-user podcast feed URL', specifying a verb, resource, and scope. It distinguishes from siblings like list_podcasts by emphasizing the private per-user nature.

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 clear context on when to use this tool (to get a private feed URL for podcast apps) and includes security warnings ('Keep the URL private'). However, it does not explicitly exclude alternative tools or mention 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, idempotentHint, destructiveHint. Description adds that it's public and lists returned fields, providing extra context 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, front-loaded with purpose, efficient, no wasted 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?

With no parameters and no output schema, the description covers purpose, usage, return content, and auth requirements. Complete for this tool.

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

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

No parameters; schema coverage 100%. Description adds meaning by detailing what each entry includes, beyond the empty 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 it returns the storyflo 6-host persona catalog with specific fields. Distinguishes from sibling tools focused on articles, digests, etc.

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 (pick a voice before rendering audio or briefing user) and that it's public with no auth. Lacks 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?

Description adds public auth requirement and data freshness details beyond annotations (readOnlyHint, idempotentHint). It explains the return contents (recency + velocity, 24h publishers, etc.), providing useful 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 concise sentences: first lists return components, second gives usage guidance. No unnecessary words, front-loaded with key 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 no output schema, description lists the major return components (top stories, publishers, daily brief, per-vertical hot lists). This is sufficient for an agent to understand what to expect, though a bit more structure detail 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 coverage is 100% and the schema already describes the 'window' parameter adequately. The description adds no new parameter-specific meaning beyond what's in the schema.

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

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

The description clearly states the tool returns a cross-vertical trending snapshot with specific components (top stories, active publishers, daily brief, per-vertical hot lists). It distinguishes from sibling tools by focusing on overall trending, not individual verticals or digests.

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 use cases: surfacing 'what's hot' or deciding which vertical to explore. While it doesn't list when not to use it or contrast with every sibling, the guidance is clear and actionable.

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, openWorldHint, idempotentHint, and no destructiveness. The description adds crucial behavioral context: premium requirement, payment settlement on Base via x402, and the challenge-response flow. No contradictions 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?

Three sentences, front-loaded with the core action, then payment details, then usage hint. 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?

Given a single parameter and no output schema, the description fully explains input constraints (vertical enum), output nature (audio briefing of top-25 last 24h), and the payment protocol (x402 challenge). No gaps for 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 has 100% enum-covered parameter 'vertical' but 0% description coverage. The tool description compensates by listing the 7 canonical values and explaining they are the only valid options, providing context beyond the enum values themselves.

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 'Fetch', resource 'stitched audio briefing', and scope 'top-25 trending articles in a single vertical from the last 24h'. This distinguishes it from siblings like 'get_audio_url' (which fetches a single audio URL) and 'digest' (likely a general summary).

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 (for a single vertical's top-25 articles within 24h) and the premium payment flow (x402 challenge). However, it does not explicitly state when not to use it or compare with alternatives like 'digest' or 'search_articles'.

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. The description adds valuable behavioral context: 'Public — no auth required' and specifies the data returned. 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?

Two sentences, front-loaded with the main purpose and outputs. Every sentence adds value with no redundancy or wasted 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?

The description fully explains the tool's output given its complexity (multiple data types) and lack of output schema. It lists all returned elements explicitly, making it 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?

Schema coverage is 100% with a clear description of the 'vertical' parameter and allowed values. The description does not add additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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 explicitly states the tool returns 'everything an agent needs to onboard a listener for a single vertical' and lists the specific outputs (top stories, host persona, premium briefing URL, RSS feed). It distinguishes from siblings by noting it replaces multiple separate tool calls.

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 clearly says 'Use after the agent has decided which vertical to set up — saves a follow-up round trip.' This provides explicit context for usage, though it does not mention 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, idempotentHint, and destructiveHint, indicating safe read operation. The description adds that it's public and requires no authentication, and details the output structure, providing useful context 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?

The description is a single well-structured paragraph that front-loads the purpose, then lists output contents and usage guidance. 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?

With no parameters and no output schema, the description fully compensates by detailing what the tool returns (show title, host, vertical, RSS feed URL, deep-link) and its usage context, making it complete for agent 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?

There are no parameters, so schema coverage is 100%. The description needs to add no param information, and it doesn't, maintaining baseline appropriateness.

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 returns the public catalog of Storyflo podcast shows, listing specific shows and entry details. It differentiates from sibling tools by focusing on listing all shows rather than retrieving individual 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?

The description explicitly says to use this tool to surface audio shows without re-deriving the catalog, and notes it's public with no auth. While it doesn't explicitly state when not to use, the context and sibling tool list imply alternatives like get_audio_url for specific shows.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which inform the agent of safe, idempotent behavior. The description adds that subscriptions are 'minted on the human's behalf', clarifying the scope. 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?

A single sentence with zero wasted words. Perfectly front-loaded and efficiently communicates the core purpose.

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 no parameters, rich annotations, and a clear description. Without an output schema, the description could hint at the structure of returned data, but it sufficiently explains the function for a simple list 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 tool has no parameters, so schema coverage is 100%. The description does not need to add parameter details; baseline for 0 params is 4. It correctly states what is returned without parameter obligations.

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 returns listener feeds (subscriptions) minted on the human's behalf, using a specific verb ('Return') and resource ('listener feed(s)'). It effectively distinguishes from siblings like 'subscribe_topic' which creates subscriptions.

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 for reviewing active subscriptions, but does not explicitly state when to use this tool versus alternatives like 'subscribe_topic' or when not to use it. No exclusion criteria or alternative guidance is provided.

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 annotations (readOnlyHint, destructiveHint false, idempotentHint true), the description adds key details: 'Pure pricing-matrix lookup; no contract is created' and 'Public — no auth required'. This fully discloses behavior without 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: first states the tool's output and nature, second gives agent a clear action step. Front-loaded, zero waste, each sentence 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?

Despite no output schema, the description explicitly lists returned items (tier, fee, revenue-share bps, contact_url). Parameters are adequately covered. This is complete for a simple lookup tool given annotations.

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 clear descriptions for both 'vertical' and 'monthly_impressions'. The description adds no further parameter-specific value, so baseline 3 is appropriate.

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 ('Return') plus resource ('partnership tier, monthly fee, revenue-share bps') and clarifies this is a 'pricing-matrix lookup' that does not create a contract. It differentiates from siblings by the output format (contact_url for human follow-up).

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 explicitly states the tool is for getting indicative pricing and instructs the agent to hand the contact_url to the human for formal partnership. It mentions 'no auth required' and 'no contract is created' but doesn't provide explicit when-not-to-use or alternatives among siblings.

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 reinforces annotations (readOnlyHint, idempotentHint, destructiveHint) and adds behavioral details: no DB row creation, no email sent, explains downstream flow. 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?

Tool description is concise (5 sentences), front-loaded with main action, 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?

Returns a URL, description explains what the URL is for and what happens after (magic link, verification). No output schema needed. Complete for the tool's purpose.

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%. Description adds context: prefill purpose, email must contain '@', magic link email sent there. Adds 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?

Clearly states it resolves a prefilled onboarding URL. Distinguishes from siblings by explicitly noting it does NOT create DB rows or send emails, setting it apart from typical registration tools.

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 context: discovery and handoff surface, safe to call speculatively, no auth required. Lacks explicit when-not-to-use but sufficient for most cases.

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 the tool as read-only, idempotent, and non-destructive. The description adds context about the return fields and vertical scoping, but does not disclose additional behavioral traits such as pagination, rate limits, or result ordering. It adds moderate value 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?

The description is concise with two clear sentences. It front-loads the core action and follows with return fields and a usage hint. No wasted words, though could add structure by separating return fields from usage instructions.

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 3 parameters, no output schema, and informative annotations, the description explains return fields and one parameter's usage. However, it omits details on limit ranges, query behavior, and result ordering. Adequate but incomplete for a search tool.

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

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

Schema description coverage is only 33%, leaving 'limit' and 'vertical' without explicit descriptions. The description repeats the enum values for 'vertical' but does not explain 'limit' semantics or how the search query behaves. It partially compensates for low coverage but is insufficient.

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 searches Storyflo's article corpus, specifying the verb 'Search' and the resource 'article corpus'. It lists return fields, which helps define the tool's output. However, it does not explicitly differentiate from sibling tools like 'get_article' or 'digest', which slightly reduces clarity.

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 a hint to 'Use vertical to scope', but no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or which sibling tools to consider in different scenarios.

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, openWorldHint, idempotentHint, and not destructive. The description adds value by confirming public operation, no auth, matching behavior (substring), and sources (FBI, CIA, etc.). This extra context beyond annotations earns a 4.

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 five sentences long, front-loaded with the core purpose, and every sentence adds distinct value (sources, matching, usage workflow, auth). No wasted words, ideal for quick comprehension.

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 lacks explicit mention of the output format or return structure (e.g., what fields are returned per case). Since there is no output schema, the description should compensate, but it only implies results via 'find a Declassified case'. Also, the limit parameter and pagination are not addressed.

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 50% schema coverage, the description restates the substring matching for 'query' but does not explain the 'limit' parameter or its purpose (default 10, range 1-50). While consistent, it adds minimal new information beyond the schema's description for query.

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 searches the Declassified archive for narrated cases from government documents. It specifies substring match across title and synopsis, and the resource 'Declassified library' is distinct from siblings like get_declassified_case (fetch full case) and digest_declassified.

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 explicitly says when to use the tool: when needing to find a case matching a topic before fetching the full case via get_declassified_case or handing the audio_url to a player. It also states public access and no auth required, providing clear context for selection.

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?

Adds rich behavioral context beyond annotations: return value is an SSE endpoint URL, event types, frame shape, replay of last ~1000 events, 30s heartbeat, public-anon read. No contradiction with annotations (all positive hints).

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?

Well-structured and front-loaded: first sentence states purpose, then consumption instructions, event types, shape, replay, heartbeat. Every sentence is useful and concise. No wasted 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?

Comprehensive for a streaming tool with multiple event types and filters. Explains consumption method, event shape, replay behavior, and heartbeat. No output schema but shape is given. Addresses all essential aspects.

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 parameter descriptions. Description mentions 'chosen filters as query params' but adds no additional meaning beyond the schema. Baseline score for high coverage is appropriate.

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 subscribes to real-time briefing-render events and returns an SSE endpoint URL, using specific verbs ('Subscribe', 'Returns'). It distinguishes itself from siblings which are mostly retrieval tools for static data.

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 clear context for usage: real-time event subscription with instructions on how to consume (EventSource, httpx.stream, curl -N). Does not explicitly state when not to use or compare to alternatives, but the unique streaming nature makes it obvious.

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?

Adds value beyond annotations by stating it does not store PII, email is informational, and RSS feed is the subscription method. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so description complements them well.

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 action, each sentence adds essential info without waste. Efficient and clear.

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 2 parameters, no output schema, and sibling context, the description fully explains output (URL, episodes_url, matched_so_far), privacy, and auth, making it complete for agent 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying email is 'informational only; no row is written for it,' which goes beyond the schema 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?

Description clearly states it resolves a podcast-feed URL for specific apps and returns JSON with episodes_url and matched_so_far. The verb 'Resolve' and resource 'podcast-feed URL' are specific, and it distinguishes from siblings like subscribe_topic by focusing on Declassified topics.

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 explicitly notes 'Public — no auth required' and 'Read-only', providing clear usage context. However, it lacks explicit guidance on when to use this tool versus sibling tools like subscribe_topic, though the name partly differentiates.

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 persistent side-effect, idempotence, replacement behavior, and stable URL. Annotations already provide idempotentHint=true and destructiveHint=false, but description adds crucial context about overwriting vs appending and single feed per listener.

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?

Well-organized into sections (behavior, when to use), front-loaded with purpose. No wasted sentences; all details earn their 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 single-parameter tool with no output schema, description covers side effects, idempotency, replacement behavior, and relationship to sibling tools. Leaves no ambiguity about usage.

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 provides full parameter details (enum, min/max, unique). Description adds behavioral context: 'replaces (not appends)' and lists allowed slugs, complementing schema without redundancy.

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 mints or updates a personalized podcast feed with specific vertical slugs. It distinguishes from sibling tools like list_subscriptions (which reads) and search_articles (which fetches articles).

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 (after setting up audio news) and when not to (not for fetching articles/audio). Provides precise guidance: call list_subscriptions first to avoid clobbering an existing feed.

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