storyflo-mcp

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

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?

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.