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 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?

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 (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=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 (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 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.