storyflo

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds that it's the 'Heaviest action' and counts more against rate limit, providing useful 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. First sentence states purpose. Second provides usage guidance and rate limit warning. No wasted words; 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?

No output schema. Description does not explain return format or pagination. For a tool with 3 params and no output schema, it covers the core idea but leaves return structure ambiguous.

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

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

Schema description coverage is 0%, so description must compensate. It maps 'top-N' to limit, 'selected verticals' to verticals, and 'requested window' to window. It adds no extra details beyond schema, so adequate but not rich.

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 verticals for a window. The title 'Build a daily digest' reinforces this. It distinguishes from siblings like get_article (single) and search_articles (search).

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

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

Explicitly says to use for 'read me today's tech news' style prompts. Warns it's the heaviest action on rate limit. Does not explicitly state when not to use, but sibling tools like get_article or search_articles provide 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 readOnly, openWorld, idempotent, non-destructive. Description adds public access info but no other behavioral details beyond that.

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 plus a brief note; no wasted words. Could be slightly more structured but efficient.

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

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

Covers purpose, use case, and window parameter; missing description for 'limit' parameter. No output schema, but for a simple tool this is adequate but not fully 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%. Description mentions 'window' values but omits 'limit' parameter entirely, leaving its meaning undocumented.

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 returns recent declassified cases with a rolling window, distinguishing it from siblings like 'get_declassified_case' (single) and 'search_declassified' (search).

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

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

Explicitly says 'Use for what's new in Declassified this week style prompts' and notes no auth required. Does not explicitly exclude alternatives but context is sufficient.

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, so the safety profile is clear. The description adds that it returns body_text and audio_url, but does not disclose other behaviors like error handling or data freshness. Adequate but not enhanced 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?

A single sentence that is front-loaded with verb and resource, no fluff. 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 read-only tool with one parameter and no output schema, the description covers the core purpose and return fields. However, it lacks details on slug format, error scenarios, and any pagination or ordering. Minimal but functional.

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%—the slug parameter has no description. The description only mentions 'by slug' without explaining format, constraints, or examples. Since the schema is bare, the description should compensate but fails to add meaningful context.

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' and the resource 'full record for an article', specifies the identifier 'by slug', and lists included fields ('body_text + audio_url'). This distinguishes it from siblings like get_audio_url (which only gets audio URL) and search_articles (which searches).

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 you have a slug and want the full article record, but it does not explicitly state when not to use it or compare to alternatives like get_audio_url or search_articles. Some implicit guidance, but not explicit.

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, and idempotentHint, but the description adds valuable context about tier-dependent behavior (stitched ad vs bare audio), which goes beyond the structured data.

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 with the core action. No fluff or redundant 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 simplicity (1 required param, no output schema), the description covers the return value (URL with tier-dependent ad behavior). It lacks explicit slug guidance, but overall is sufficiently complete 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?

With 0% schema description coverage, the description should compensate for the single parameter 'slug'. It only mentions 'for an article' without explaining what 'slug' is, its format, or how to obtain it. Minimal value added over 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 action ('resolve the playable audio URL') and the resource ('for an article'). It distinguishes behavior by tier (free vs plus/pro), setting it apart from sibling tools like get_article 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 provides no guidance on when to use this tool versus alternatives, such as when to prefer get_article for text content or search_articles for discovery. There are no when-not-to-use instructions.

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. The description adds significant behavioral details beyond annotations: fail-closed behavior when config is off, attribution-aware via embedder_slug, and no persistent server state. 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?

The description is well-structured with clear sections (Behavior, When to use). It is slightly verbose but every sentence adds necessary context, such as the editorial posture and fail-closed behavior. 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?

Given the rich annotations and full schema coverage, the description is highly complete. It addresses error conditions, attribution, idempotency, and proper usage context. No output schema exists, but the return value (a URL) is adequately described.

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 value: clarifies asset is case-insensitive and upper-cased, explains embedder_slug defaults to 'storyflo' when omitted. These details go beyond the schema 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 returns a Kraken affiliate URL for a given crypto asset. It distinguishes itself from sibling tools by emphasizing it is an editorial linkout, not a trading prompt, and specifies the URL points to a public asset page.

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: 'Surface the link in show-notes copy or in MCP-client renderings of a crypto-relevant story.' Also provides a clear exclusion: 'DO NOT inline the URL into spoken audio narration without the host-read line that frames it as an editorial signal.' This is exemplary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it is 'Public — no auth required,' which is valuable 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?

Two sentences, no wasted words. Front-loaded with the core action, followed by specifics and usage guidance.

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 simple tool (single parameter, read-only, public), the description covers all necessary context: what it does, what it returns, when to use it, and authentication requirements.

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 for the slug parameter. The description adds that the slug is 'as returned by search_declassified,' providing helpful contextual 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?

The description clearly states the verb ('Fetch') and the resource ('full record for a Declassified case by slug'). It lists specific fields returned and distinguishes itself from sibling tools like 'search_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?

Explicitly states when to use this tool: 'Use after search_declassified when the agent needs the full case body to summarize, narrate, or hand off audio playback.' Provides clear context and 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it never returns raw external market odds, is original analysis, and includes citation instruction. 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?

The description is well-structured with a clear opening sentence followed by details. It is slightly verbose but every sentence adds value. Could be more concise 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?

No output schema, but the description lists all return fields comprehensively. It also covers auth status, filtering, and disclaimers. For a simple list tool with two optional parameters, this is fully 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 100%, so baseline is 3. The description restates the schema's descriptions for limit and source without adding new semantic meaning. It does not compensate further beyond confirming the 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?

The description clearly states it returns Storyflo's computed divergence index between prediction markets and media narratives, specifying what data it includes and excludes. It distinguishes from siblings like get_market_linked_stories by emphasizing original analysis and the unique divergence metric.

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: public, no auth required, not investment advice, and mentions filtering by source. However, it does not explicitly state when to use this tool over alternatives, though the sibling context is available.

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, and destructiveHint. The description adds value by confirming the tool is public and requires no authentication, and describes the content of the manifest. 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?

The description is two sentences, front-loading the endpoint and content. Every sentence is informative, with no redundant 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?

Given the tool has one required parameter, no output schema, and the description explains the manifest's contents, it is fairly complete. Minor omission: no mention of response format or size, but not critical.

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 'slug' parameter. The description does not add additional semantic meaning beyond the schema; it merely mentions the slug in context. 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 clearly states the tool wraps a public manifest endpoint and lists its contents (creative formats, voice options, payout config, beacon URLs). It distinguishes from siblings like register_embedder and get_embedder_network_manifest by specifying usage context.

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 use cases: after register_embedder or when reading another partner's manifest for ad planning. It also notes the tool is public with no auth required. While it doesn't list when not to use, the guidance is sufficient for an agent.

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, destructiveHint false. The description adds valuable context: it wraps a public endpoint, is a platform-level bundle, and describes the contents. 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?

Three sentences, front-loaded with purpose, then usage scenarios, then auth note. No fluff. 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?

Given no output schema and no parameters, the description provides sufficient context: lists contents, usage scenarios, auth. Could hint at response format but not necessary for selection.

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, so baseline is 4. The description mentions the endpoint path but no further parameter details needed. Schema coverage is 100% trivially.

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 a specific endpoint and lists its contents (supported creative formats, payout rails, attribution URLs, integration patterns). It distinguishes itself from the sibling tool 'get_embedder_manifest' by specifying 'platform-wide' and 'network manifest', providing clear purpose.

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: when evaluating whether to wire storyflo into a surface, or when a DSP partner needs the canonical integration shape. Also notes 'Public — no auth required', giving 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?

The description discloses key behavioral traits beyond annotations: it states the tool is an 'editorial sourcing surface, not market-data redistribution' and explicitly lists what it never returns (raw prices, market-implied probabilities, volumes, open interest). This aligns with annotations (readOnlyHint, idempotentHint) and adds valuable 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?

The description is two paragraphs: first explains the tool's purpose and what it returns, second provides usage guidance and filter options. It is concise but could be slightly more compact. Every sentence adds value, and it's well-structured for an agent.

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 explains the return shape: items carry signal tags and a link-out to Kalshi. While it doesn't specify full fields (e.g., title, date), it provides sufficient context for an agent to understand the tool's outputs. The tool is simple (list of stories) so completeness is adequate.

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% (limit has no description). The description adds meaning for the signal parameter by explaining the values 'high_velocity' and 'genuine_uncertainty'. For category and vertical, it adds examples but little additional semantics beyond the schema. Overall, it improves parameter understanding moderately.

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 'Storyflo stories that match an actively traded event contract on Kalshi', specifying the verb 'get', the resource 'stories', and the unique context of active event contracts. It distinguishes from sibling tools like search_articles by focusing specifically on market-linked 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?

The description provides explicit usage guidance: 'Use this when the agent needs to know which Storyflo stories are about news themes that have an actively traded event contract' with concrete examples. It also clarifies what the tool does not return (raw prices, probabilities). While it doesn't list alternative tools for exclusions, the positive context is strong.

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 context about identity resolution via OAuth and zeroed shape for anonymous callers, going 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?

Three sentences with no wasted words. First sentence states purpose and outputs, second explains identity handling, third lists use cases. Front-loaded and efficient.

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

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

For a zero-parameter tool with rich annotations, the description fully covers purpose, identity handling, use cases, and return fields. No gaps remain given the tool's simplicity.

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, and schema coverage is 100%. The description adds value by listing the returned fields (total calls, success rate, etc.) and explaining identity handling, which compensates for the absence of output 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 verb 'Return' and the resource 'caller's own trailing 30-day MCP tool-usage summary', listing specific fields. It distinguishes from siblings by focusing on self-usage metrics.

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 use cases: self-budgeting against rate limits, auditing tool usage, and deciding on paid tier. It also notes behavior for anonymous callers. However, it does not explicitly state when not to use it or compare to 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?

The description adds significant behavioral context beyond annotations: it mentions token creation on first call (mutation), idempotency, the unguessable URL path, and security warnings (keep URL private). This complements the annotations which indicate idempotence and non-destructiveness.

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, front-loading the core function and then providing necessary context. Each sentence adds value, though the explanation of the daily brief could be slightly more concise. Overall efficient.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, security, token lifecycle, and authentication. It omits the exact output format, but this is a minor gap given the tool's simplicity.

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 description echoes the parameter's schema description without adding new semantic constraints or format details. It reinforces the source of the token but does not extend 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?

The description clearly states the tool returns the caller's private podcast feed URL, explaining it's a personalized daily brief and distinguishing it from siblings like get_audio_url or 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 explains how to use the tool (pass listener_token) and the context (private feed model), but does not provide explicit guidance on when to use this tool versus alternatives like get_audio_url or list_podcasts, leaving inference to the agent.

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. The description adds that the tool is public and requires no authentication, and it lists the returned fields. With annotations covering safety, the description provides complementary 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 sentences with no redundancy: first sentence specifies the return value and fields, second sentence gives usage guidance and access info. Front-loaded and efficient.

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

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

Despite no output schema, the description fully lists the fields returned, and the usage context is clear. For a simple parameterless read tool, this is complete.

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

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

There are zero parameters, so baseline is 4. The description does not need to add parameter meaning but still adds value by explaining the output fields. Schema coverage is 100%, meeting the 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?

The description clearly states the tool returns the storyflo 6-host persona catalog, listing specific fields like slug, name, voice_id, etc. It uses a specific verb 'Return' and resource 'host persona catalog', distinguishing it from sibling tools like get_audio_url.

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 usage context: 'Use this to pick a voice for the agent's use case before rendering audio or briefing the user.' It also notes 'Public — no auth required.' However, it does not explicitly state when not to use or mention 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds value by stating 'Public — no auth required' and explaining the window parameter's advisory nature (rolling 24h, future expansion). 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 without unnecessary words. Each sentence serves a purpose: describing output, providing usage guidance, and stating auth requirements. Front-loaded with the primary function.

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 exists, but the description adequately explains the return values (top stories, publishers, daily-brief, per-vertical lists). It also covers the window parameter semantics. All essential context is provided for an agent to use 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 provides 100% coverage for the single parameter, including a detailed description. The tool description does not add additional parameter information beyond what is in the schema. Baseline score 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 it returns a 'cross-vertical trending snapshot' with specific components (top stories, active publishers, daily-brief, per-vertical lists). It distinguishes itself from sibling tools like get_vertical_briefing and get_vertical_landscape by emphasizing the cross-vertical aggregation.

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: 'to surface what's hot on storyflo right now' or to decide which vertical landscape to dig into next. Also states 'Public — no auth required', clarifying accessibility and avoiding unnecessary auth checks.

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 (readOnlyHint, destructiveHint) indicate safe read. Description adds payment mechanism and x402 challenge flow, which are behavioral traits beyond 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?

Three sentences, 48 words. Front-loaded with core action, then payment info, then allowed values, then call flow. Every 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?

For a 1-param tool with annotations and no output schema, description is quite complete. Explains briefing content, verticals, payment, and call flow. Could clarify the response format after successful payment.

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 1 enum parameter with 0% description coverage. Description explicitly lists all allowed values and explains they are canonical verticals, adding 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 fetches a stitched audio briefing of top-25 trending articles in a single vertical from last 24h. It explicitly lists the canonical verticals and distinguishes from siblings like 'get_article' or 'digest'.

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 usage context: for a specific vertical, premium service with x402 challenge. Describes the two-step call flow. However, it doesn't explicitly mention when not to use or compare to 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, openWorldHint, idempotentHint, destructiveHint=true. Description adds context about the x402-gated URL and that the tool is one-shot, but does not contradict annotations. No additional behavioral risks disclosed 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 sentence that front-loads the main purpose and lists returned items efficiently. However, it is somewhat long; could be slightly more concise without losing clarity.

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, the description fully explains what is returned and the context of use. It covers the alternative tools and the gated nature of one URL, providing complete guidance.

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 listing valid slugs. The description does not add new meaning beyond what the schema provides, 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 returns everything needed to onboard a listener for a single vertical, listing specific items (top stories, host persona, URLs). It distinguishes from sibling tools by noting it saves round trips to get_personas, search_articles, and get_premium_briefing.

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 after the agent has decided which vertical to set up' and mentions it avoids follow-up calls. Also notes 'Public — no auth required.' Provides clear when-to-use and alternative avoidance.

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, and destructiveHint. The description adds 'Public — no auth required' and details about the return fields, which is useful context. However, the behavioral traits are largely covered by annotations, so the description adds moderate value beyond them.

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 extraneous words. The main purpose is front-loaded, and every sentence serves a purpose (listing shows, describing entry fields, usage note).

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 parameters and no output schema, the description fully specifies what the tool does and what it returns. The details about entry fields and the use case are sufficient for an agent to understand invocation and output.

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 no parameters, the baseline is 4. The description adds meaning by explaining what the tool returns (list of shows with detailed entries), which goes beyond the empty input 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 explicitly states it returns the public catalog of Storyflo podcast shows, listing specific shows (Declassified archive plus 6 daily-brief shows) and detailing what each entry contains (title, host name, vertical, RSS URL, deep-link). It distinguishes from siblings by noting that this avoids re-deriving the catalog from URL patterns.

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 says 'Use to surface every audio show an agent can offer its user', providing clear context for when to use. It also mentions it avoids re-deriving from URL patterns. However, it does not explicitly exclude other tools or mention alternatives, though the sibling context implies other tools handle specific podcasts.

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. Description adds useful context about acting on behalf of a human, but does not disclose other behaviors like pagination or rate limits. Overall 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?

Single sentence, zero waste. Efficiently conveys purpose without unnecessary 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 no parameters, no output schema, and simple read-only retrieval, the description fully covers what the tool does. No additional context 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?

Tool has 0 parameters, baseline 4 applies. Description does not need to add parameter info as there are none.

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 'Return the listener feed(s) this agent has minted on the human's behalf.' Uses specific verb 'Return' and resource 'listener feed(s)/subscriptions'. Distinguishes from sibling 'subscribe_topic' by being the inverse operation.

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 guidance on when to use vs alternatives like 'search_articles' or 'digest'. The phrase 'on the human's behalf' implies context but lacks when-not-to-use or alternative suggestions.

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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating it's a pure lookup with no contract creation. It adds that no auth is required and that the agent should delegate to a human for next steps. This provides full transparency 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 extremely concise with two sentences. The first sentence clearly states the output, and the second sentence adds critical behavioral context and instructions. No superfluous 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?

Given the tool has 2 parameters and no output schema, the description fully compensates by listing the returned fields (tier, fee, bps, contact_url) and explaining the tool's nature. It provides everything an agent needs to use it 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% and both parameters ('vertical', 'monthly_impressions') are described in the schema. The description does not add further context or examples for these parameters, so it meets the baseline expectation without exceeding 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 explicitly states it returns an indicative partnership tier with specific details (tier name, monthly fee, revenue-share bps). The verb 'Return' and resource 'partnership tier' are clear. Unlike sibling tools focused on articles, embedders, or subscriptions, this is a pricing lookup tool, making it distinct.

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 clarifies this is a pure pricing-matrix lookup and notes no contract is created. It instructs the agent to hand the returned contact_url to the human for formal partnership. While it doesn't explicitly state when not to use or mention alternatives, the context is clear for an agent to select this tool when a pricing quote is needed.

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. Description adds significant value beyond annotations by emphasizing that the tool DOES NOT create a DB row or send email, and explains its role as a speculative discovery surface. 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?

Single well-structured paragraph that front-loads the main action and includes important caveats. Every sentence adds value, though it could be slightly more concise without losing clarity.

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's simplicity (3 params, no output schema), the description fully explains what is returned (URL), the human action needed, and the follow-up process. Agent can correctly understand input/output and idempotent behavior.

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 all 3 parameters described. Description adds only minor context ('prefilled with') but does not significantly expand on schema descriptions. Baseline 3 is appropriate as description adds minimal extra 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 it resolves the storyflo embedder onboarding URL prefilled with name/email/vertical, distinguishing it from actual registration by explicitly noting it does NOT create a DB row or send email. The verb 'resolve' and resource 'onboarding URL' are specific, and the purpose is distinct from sibling tools like get_embedder_manifest.

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 'discovery + handoff' and can be called 'speculatively without triggering inbox-bound email.' It implies when not to use (when actual registration or email is needed) but does not name a specific alternative tool. Clear context but no explicit exclusion.

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 (readOnlyHint, destructiveHint, idempotentHint) already indicate a safe, idempotent read operation. Description adds the specific fields returned, which is useful 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 concise sentences: first defines purpose and output, second provides scoping guidance. No fluff, 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?

Covers parameters and return fields adequately for a simple search tool with good annotations. Lacks explanation of result ordering or pagination beyond the limit parameter, but not critical for basic 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 description coverage is only 33% (only query has a description). The description compensates by listing valid vertical values and implying the use of limit for result count. For vertical, it enumerates all enum values, adding significant 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?

Specifies the verb 'Search', the resource 'Storyflo's article corpus', and lists exact return fields (slug, title, publisher, vertical, snippet, audio_url, listen_seconds). Clearly differentiates from sibling tools like get_article (single article) and get_audio_url (specific audio).

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 to use the vertical parameter to scope searches, listing valid values. Does not explicitly state when not to use, but the context of searching the whole corpus vs. getting a specific article is implied by sibling tool names.

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 context: substring match across fields, sources from government documents, and no auth needed. 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-loaded with purpose and usage. Every sentence adds value with no waste.

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?

Simple tool with 2 params, no output schema. Description covers behavior, usage, examples, and public access. Annotations provide safety profile. Fully 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?

Schema describes query param well and limit with constraints. Description reinforces query substring matching but adds no extra semantics beyond schema. Schema coverage 50%, but description doesn't compensate significantly.

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 Declassified archive' with verb 'Search' and resource. It distinguishes from siblings like 'get_declassified_case' by specifying substring matching on title and synopsis.

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: use when needing to find a declassified case by topic before fetching full case via 'get_declassified_case' or handing audio URL to a player. Also notes 'Public — no auth required'.

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 adds rich behavioral context beyond annotations: 'Public-anon read', 'replays last ~1000 events on connect', 'heartbeat every 30s', event types, and frame shape. Annotations already indicate read-only, idempotent, non-destructive, and open world, and the description aligns perfectly 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?

Three sentences, front-loaded with the primary action. Every sentence adds value: subscription, endpoint usage, event types/frame shape, replay/heartbeat behavior. 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?

No output schema exists, but the description fully specifies the event frame shape, replay behavior, heartbeat, and parameter usage. For a streaming tool that returns an SSE URL, this covers all necessary behavioral and return value 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 100% and description explains that filters become query params in the SSE endpoint URL. While parameters are simple filters, the description adds useful context beyond schema (query param integration). Baseline 3 with credit for extra 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 subscribes to real-time briefing-render events, returns an SSE endpoint URL, and lists event types. The tool's purpose is distinct from siblings, none of which are SSE streaming 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?

The description provides explicit client-side implementation guidance (EventSource, httpx.stream, curl -N) and explains the endpoint behavior. While it doesn't explicitly state when not to use, the streaming context is clear and no sibling offers SSE, so no exclusion needed.

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 significant context beyond annotations: explicitly states read-only, no email/PII storage, no auth. Aligns perfectly with readOnlyHint=true, idempotentHint=true, destructiveHint=false.

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 with a distinct purpose: primary action, return values, behavioral traits. 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?

Covers all essential aspects for an agent to invoke correctly: purpose, return values (feed URL, episodes_url, matched_so_far), privacy, and auth. 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?

Schema descriptions already cover both parameters (topic required, email optional). The description provides no additional parameter-level detail beyond what the schema offers. Baseline 3 due to 100% schema 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 the tool resolves a podcast-feed URL for a specific (Declassified) topic and returns JSON data. Distinguishes itself from generic subscribe_topic sibling by focusing on Declassified cases.

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?

Describes the primary use case (subscribing via podcast apps) and clarifies read-only, no PII storage, no auth. Lacks explicit comparison to sibling tools like subscribe_topic, 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 provide idempotentHint=true and destructiveHint=false. Description adds behavioral details: persistent server-side side-effect, idempotent on identical input, replaces on different input, single feed per listener. 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?

Well-structured with clear sections (Behavior, When to use). Every sentence adds value, though slightly verbose. No wasted words, but could be more 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?

Given the tool's simplicity (1 param, no output schema, clear annotations), the description is fully complete. It covers all necessary behavioral aspects and usage guidance.

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 for 'verticals' parameter. Description reinforces the allowed values and the replacing behavior. Baseline 3 is appropriate as the description does not add much 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 the tool's purpose: 'Mint or update the human's personal Storyflo podcast feed.' It uses specific verbs (mint/update) and resources (podcast feed), and distinguishes from siblings like list_subscriptions, search_articles, get_audio_url.

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 the agent has been asked to set up audio news...' and when not to use: 'Do NOT use to FETCH articles or audio — that's search_articles + get_audio_url.' Also provides alternative tool names and precaution: '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.