Storyflo

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

Beyond the annotations (readOnlyHint, destructiveHint), the description adds the key behavioral note that this is the 'heaviest action' and counts more against the per-agent rate limit. This is useful context not present in the annotations, aiding in cost/rate management.

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: the first defines the action and scope, the second adds a use-case example and rate-limit warning. Every sentence is purposeful, with no redundancy or filler. Front-loaded with 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 description covers the tool's purpose, usage context, and a critical rate-limit caveat, making it reasonably complete for a simple read-only tool with no output schema. It does not mention that verticals is optional or the default window, but those are captured in the schema, and the description adds enough to avoid major confusion.

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

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

Schema description coverage is 0%, so the description compensates by explaining 'top-N' (limit), 'selected verticals' (verticals), and 'requested window' (window). This gives functional meaning to all three parameters, though it does not enumerate allowed enum values (those are in the schema).

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

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

The description clearly states the tool aggregates top-N articles across verticals for a time window, with a specific verb ('Aggregate') and resource ('articles'). However, it does not explicitly differentiate from sibling tools like digest_declassified or get_vertical_briefing, so it lacks explicit sibling differentiation.

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

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

Gives a clear usage context with the example prompt 'read me today's tech news' and warns that it is a heavy action for rate limits. It does not mention specific alternatives or when not to use it, but the context is sufficient for typical use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the rolling window behavior and 'Public — no auth required', which goes beyond the annotations. It does not mention pagination or ordering beyond 'most-recently-published', but the annotations cover the safety profile.

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

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

The description is two sentences, front-loaded with the core purpose, then adding usage and parameter semantics. Every word earns its place with no fluff or repetition of schema details.

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

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

For a simple list-retrieval tool with only two parameters and strong annotations, the description covers purpose, usage, window semantics, and auth requirements. The lack of an output schema is not a significant gap since the return format is straightforward for a list of recent cases.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to the 'window' parameter by explaining the values: 'window=today (~24h) | week (default) | month.' It does not explain 'limit', but that parameter is simple and has clear schema constraints, making it less critical.

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's function: 'Return the most-recently-published Declassified cases over a rolling window.' It specifies a distinct resource ('Declassified cases') and a specific behavior (most-recently-published, rolling window), which differentiates it from siblings like search_declassified and get_declassified_case.

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

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

Provides explicit usage guidance: 'Use for "what's new in Declassified this week" style prompts.' This clearly indicates when to use the tool, but does not explicitly name alternatives or when-not-to-use, so it falls short of a 5.

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, and destructiveHint=false, covering safety traits. The description adds that the record includes body_text and audio_url, which is useful return-content context beyond the annotations, but does not disclose any additional behavioral traits like error handling or rate limits. This aligns with the 'annotations present' baseline.

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

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

The description is a single, well-structured sentence that is immediately clear and front-loaded. Every word adds value, with no filler or redundant phrasing.

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 parameter) and the presence of annotations covering safety, the description is largely complete. It mentions the key return fields (body_text + audio_url) despite no output schema. It does not describe error behavior or edge cases, but for a straightforward fetch tool, this 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?

Schema description coverage is 0%, so the description must compensate. It only mentions 'by slug', which essentially repeats the parameter name without adding meaning (e.g., format, example, or what a slug is). With no other context, the description fails to enrich the parameter beyond its name.

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 the specific verb 'Fetch' and identifies the resource ('article') and the key identifier ('by slug'). It also lists key fields returned ('body_text + audio_url'), which clearly distinguishes it from sibling tools like search_articles (which searches) and get_audio_url (which returns only a 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 clearly implies use when you have a slug and need the full article record. No explicit exclusions or alternatives are named, but the context is unambiguous. A score of 4 is appropriate because it provides clear context without explicit when-not 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 provide readOnly, idempotent, and non-destructive hints. The description adds tier-dependent output behavior (stitched-with-ad vs bare audio), which is valuable and not derivable from annotations or schema. This exceeds the baseline expectation.

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, both informative and free of redundancy. The main action is front-loaded, and the second sentence adds a meaningful nuance about tiers. 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?

For a simple one-parameter resolver with robust annotations, the description covers the core purpose, the input implied by 'article', and the output type (URL). No output schema exists, so the return description suffices. Edge cases are not necessary at this complexity level.

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 only 'slug' with no description, and schema coverage is 0%. The description clarifies that the slug refers to an article, but does not explain the slug format or how to obtain it. It offers partial compensation for a simple parameter but not complete semantics.

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

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

The description clearly states the tool's function with a specific verb 'Resolve' and a specific resource 'playable audio URL for an article'. It distinguishes itself from siblings like get_article by focusing on audio URL resolution. The tier-dependent return detail further anchors its 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?

The description implies when to use it: 'for an article' indicates it pairs with an article identifier (slug). It doesn't explicitly name alternatives or exclusion criteria, but the context is clear. Lacks explicit 'use this instead of...' guidance, so not a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses 'No persistent server state,' 'Fail-closed' behavior in detail, and 'Attribution-aware' behavior with the default ?ref=storyflo. It also explains that an error structure is returned rather than a half-formed URL. No contradictions with annotations.

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

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

The description is structured with a purpose paragraph, a Behavior bullet list, and a When-to-use section. While somewhat long for a simple URL-returning tool, every section adds valuable context—especially the compliance-sensitive framing. It is front-loaded and avoids tautology.

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

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

Despite lacking an output schema, the description clearly indicates the primary return value (a URL) and the fail-closed error structure. It covers purpose, behavior, and usage. A minor gap is the absence of the exact error response shape, but this is not critical 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 schema descriptions already document asset case-insensitivity/upper-casing and embedder_slug's default ?ref=storyflo behavior. The description's Behavior section restates this without adding new parameter-specific details, so the 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 opens with a clear, specific purpose: 'Return Storyflo's markets-partner Kraken affiliate URL for a given crypto asset (BTC, ETH, etc).' It immediately distinguishes the tool from siblings by emphasizing the editorial linkout nature and 'Markets-as-INPUT' posture, and the resource (affiliate URL) is unambiguous.

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

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

The 'When to use' section explicitly states usage in show notes or MCP-client renderings, and provides a clear exclusion: 'DO NOT inline the URL into spoken audio narration without the host-read line.' This is explicit contextual guidance, even naming a specific condition for when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond this by disclosing the exact return payload (title, summary, transcript_excerpt, episode_date, duration_sec, agency, audio_url, source_doc_url, up to 5 related cases) and explicitly stating 'Public — no auth required,' which is not fully covered by the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause earns its place. It efficiently conveys return fields, usage context, and authentication status without redundant wording.

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

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

For a simple lookup tool with one parameter and no output schema, the description is complete: it lists the return fields, explains the intended workflow (after search_declassified), and states auth requirements. No critical information is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% for the single parameter 'slug', with the schema describing it as 'Case slug as returned by `search_declassified`.' The tool description adds no additional parameter semantics beyond what the schema already provides, so the 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 a specific verb ('Fetch') and resource ('full record for a Declassified case by slug'), and it lists the distinct return fields, which distinguishes it from sibling tools like search_declassified (which returns search results) and get_audio_url (which likely returns only the 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 explicitly states when to use the tool: 'Use after `search_declassified` when the agent needs the full case body to summarize, narrate, or hand off audio playback.' This gives clear context and sequencing. However, it does not explicitly mention when to use an alternative (e.g., get_audio_url for audio-only needs), so it lacks an explicit exclusionary guideline.

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 read-only/idempotent/non-destructive. The description adds substantial context: it never returns raw external odds, requires no auth, includes a citation expectation, is not investment advice, and explains the computation basis from market contracts and news stories. This exceeds annotation coverage.

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 a clear definition and each sentence contributes substantive detail about the metric, returns, restrictions, and caveats. Slightly dense but no wasted words; appropriate length for the complexity.

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

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

With no output schema, the description lists the returned fields per item (divergence value, news-narrative probability, market descriptor, story links, venue link), covers filtering, auth, and disclaimers. This is sufficient for an agent to correctly invoke and interpret results, though it omits edge cases like empty results.

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

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

Input schema has 100% coverage for both parameters (limit with min/max/default, source with allowed values). The description only restates 'Filter by source' without adding new semantics. 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 it returns Storyflo's computed divergence index, explaining the metric (gap between market-implied and news-narrative probabilities), ranking by absolute divergence, and listing returned attributes. It distinguishes the tool as 'ORIGINAL ANALYSIS... not market-data redistribution,' setting it apart from sibling 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 gives clear context on what the tool offers (original analysis, not raw odds) and notes it's public/no auth. It excludes raw market odds but does not explicitly name alternative tools for that need, so it falls short of explicit when-to-use/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, and destructiveHint=false. The description adds the important context that the endpoint is public with no auth required, which is behavioral info not present in the annotations. It also explains the data bundle's purpose without contradicting the annotations.

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

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

The description is two sentences: the first defines the resource and its contents, the second gives usage context and auth status. Every sentence adds value with no redundancy or filler.

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

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

For a simple single-parameter GET with a rich annotation set and clear sibling context, the description fully covers the tool's purpose, usage timing, and access requirements. The lack of an output schema is acceptable given the straightforward nature of fetching a manifest.

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 is only one parameter (`slug`) and schema description coverage is 100%, with a clear example provided. The description reinforces that the slug is part of the URL path but adds no new semantics beyond the schema, warranting the baseline score for high 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?

The description clearly states the tool wraps the public `/embed/<slug>/manifest.json` endpoint, identifying the specific resource (per-embedder manifest) and the verb (get). It also lists the manifest's contents (creative formats, voice options, payout config, beacon URLs), distinguishing it from the network-level sibling `get_embedder_network_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?

The description explicitly says to use it after `register_embedder` or when reading another partner's manifest to plan an ad buy. This provides clear usage context, though it doesn't mention when not to use it or name alternatives such as `get_embedder_network_manifest`.

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=false. The description adds further context by stating 'Public — no auth required' and clarifying it wraps a public endpoint. This goes beyond the annotation hints and helps the agent understand access requirements and the tool's passthrough nature.

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

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

The description is compact (~60 words) and front-loaded. The first sentence identifies the endpoint and its contents, the second provides usage scenarios, and the third handles authentication. Every sentence contributes new information with no redundancy or filler.

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

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

For a zero-parameter read-only tool with no output schema, the description covers the essential context: what the manifest is, what it includes, when to use it, and authentication. It does not need to describe return values as the listed contents inform the agent of the response shape, and the provided annotations cover the operational safety profile.

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 zero parameters, and schema description coverage is 100%. Per the rubric, baseline is 4 when there are no params. The description appropriately avoids inventing parameter details, and no compensation is needed since there is nothing to document.

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

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

The description clearly states the tool wraps the public `/embed/network-manifest.json` and defines it as the platform-level DSP/SSP onboarding bundle. It lists the contained elements (creative formats, payout rails, attribution URLs, integration patterns) and distinguishes it from sibling `get_embedder_manifest` by specifying 'platform-wide' and 'network 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?

The description provides explicit when-to-use guidance: 'Use when an agent is evaluating whether to wire storyflo into its surface, or when a DSP partner needs the canonical integration shape.' It does not explicitly name when-not-to-use or alternative tools, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, and the description adds meaningful behavioral context: it returns qualitative tags and a link-out to Kalshi, while explicitly excluding raw market data. This clearly communicates what the tool does and does not expose.

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 and front-loaded with the core definition, followed by return details, exclusions, usage guidance, and filter options. Every sentence contributes meaningful information without redundancy, making it appropriately concise for the tool's complexity.

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

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

With no output schema, the description adequately describes the returned items as carrying signal tags and a link-out, and clarifies the data exclusions. It covers use cases, examples, and filters, but could be slightly more explicit about the exact item shape or sorting behavior, though the provided info is likely 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 schema covers the signal, category, and vertical parameters with descriptions, leaving only 'limit' without prose. The description restates the three filter dimensions but does not add new parameter semantics beyond what the schema already provides, so it meets the baseline for high 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?

The description clearly states this tool returns Storyflo stories that match actively traded event contracts on Kalshi, distinguishing it from market-data tools by emphasizing it is an editorial sourcing surface. It also names the specific qualitative signal tags and link-out behavior, making the purpose unambiguous.

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

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

The description explicitly says 'Use this when the agent needs to know which Storyflo stories are about news themes that have an actively traded event contract' and provides examples. It also includes a when-not by stating the tool 'never returns raw prices, market-implied probabilities, volumes, or open interest,' though it does not name sibling 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, idempotentHint, destructiveHint, so the safety profile is well covered. The description adds meaningful context beyond annotations by explaining identity resolution from the bearer token and the zeroed shape for anonymous callers, which is a non-obvious behavioral trait. This is solid but not extensive, earning a 4.

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

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

The description is three sentences, each with clear purpose: what it returns, how identity works, and when to use it. It is front-loaded with the core purpose and avoids redundant phrases. No filler or repetition of the title/name.

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

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

With no output schema, the description fully compensates by itemizing the return metrics (total calls, success rate, p50 latency, per-tool counts) and describing the anonymous case. Combined with strong annotations and zero parameters, this is complete for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. With 0 params, the baseline is 4 and no parameter description is needed. The description focuses on output composition and usage context, which 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 opens with a specific verb and resource: 'Return the caller's own trailing 30-day MCP tool-usage summary.' It enumerates exactly what the summary contains (total calls, success rate, p50 latency, per-tool counts), clearly distinguishing this tool from siblings like get_my_private_feed or get_trending_topics.

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

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

The description gives clear use cases: 'self-budget against rate limits, audit which tools your agent actually uses, or decide whether a paid tier is worth the spend.' It also explains the auth context (OAuth bearer token, anonymous zeroed shape), but does not explicitly state when not to use it or name alternatives. Clear context, no exclusions, so a 4 is appropriate.

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?

Goes far beyond the annotations: discloses the token lives in the URL path, is unguessable and fetchable over HTTPS, is minted on first call and stable thereafter, and warns that anyone with the URL can subscribe. Also clarifies the authentication model (listener_token as credential, no OAuth). This is rich behavioral context that annotations do not provide.

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

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

The description is more verbose than minimal but every sentence adds value: purpose, usage, formatting, privacy warning, and credential details. The structure flows logically from what to what to how, with no filler.

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

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

Given the tool's complexity (token-based auth, privacy implications, persistent minting), the description covers all essential aspects: what it returns, how to invoke it, what the credential is, the security model, and the behavior on first call. No output schema exists, but the description mentions the return value ('feed_url') sufficiently.

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

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

The schema already documents the listener_token with a description, and the description reinforces it by explaining its role as identity and where to get it. The description adds the link between the token and the minting behavior, but the schema already covers the semantics well, so this is solid but not exceptional.

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

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

The description opens with a specific verb and resource: 'Return the caller's PRIVATE per-user podcast feed URL.' It clearly distinguishes this from sibling tools like list_podcasts and get_audio_url by emphasizing the private, personalized, per-user nature and the delivery mechanism (podcast apps).

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

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

The description provides clear when-to-use context: it explains the private-feed model, how to obtain the URL, and how to use it ('paste the returned feed_url into the app's "Add a show by URL"'). It does not explicitly name alternatives or exclusion criteria, but the usage context is unambiguous.

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 read-only, idempotent, and non-destructive hints. The description adds valuable context beyond annotations, such as 'Public — no auth required' and the specific return contents. No contradiction with 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 well-structured sentences with the main purpose front-loaded. Every sentence adds useful information, and there is no redundancy or filler.

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

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

For a zero-parameter, read-only tool with no output schema, the description is thorough: it names the catalog, lists all contained fields, explains the use case, and states access requirements. It is fully complete for its complexity level.

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 zero parameters, so the schema provides full coverage (100% empty schema). The description adds value by enumerating the output fields (slug, name, voice_id, owned verticals, tone archetype, sign-off line, URLs), which helps the agent understand what to expect. Baseline 4 is appropriate.

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

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

The description uses a specific verb ('Return') and names the exact resource ('storyflo 6-host persona catalog') with a detailed list of included fields. It clearly distinguishes itself from sibling tools by focusing on host personas rather than articles, briefings, or manifests.

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

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

It explicitly states when to use the tool: 'Use this to pick a voice for the agent's use case before rendering audio or briefing the user on which host covers which vertical.' It also notes no auth is required. It doesn't mention when not to use it or alternatives, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond this: 'Public — no auth required' and the rolling 24h nature of the 'today' snapshot. There is no contradiction; the description reinforces the read-only, non-destructive nature.

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 filler. The first sentence front-loads the return payload, the second gives usage context and auth status. Every word serves a purpose, making it concise and well-structured.

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, so the description carries the burden of describing the returned data, which it does by listing the components (top stories, active publishers, daily-brief, vertical hot lists). Combined with a single documented parameter and clear annotations, the tool is fully understood for selection and invocation.

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

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

Schema coverage is 100% with the window parameter fully described in the schema (enum, default, and advisory note about rolling 24h). The description adds no additional parameter-specific meaning, so it rightly relies on the schema. 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 opens with a specific verb and resource: 'Return storyflo's current cross-vertical trending snapshot', enumerating exact contents (top stories, active publishers, daily-brief, per-vertical hot lists). This clearly distinguishes it from sibling tools like get_vertical_briefing or get_vertical_landscape by emphasizing 'cross-vertical' and 'trending'.

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

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

The description explicitly says 'Use when the agent needs to surface what's hot on storyflo right now' and 'or to decide which vertical landscape to dig into next'., providing clear context. It also states 'Public — no auth required', aiding usage. However, it does not name specific alternative tools, so it stops short of a fully explicit when-not-to-use.

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 signal readOnly, openWorld, idempotent, and non-destructive. The description goes further by disclosing the payment requirement, the x402 challenge on first call, the need to sign and retry, and the audio output format — behavioral details not present in 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?

Four dense sentences with no filler. The first sentence states the core function, followed by payment, validation, and authentication flow — each sentence serves a distinct 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?

For a tool with no output schema, the description explains what is returned (audio briefing), the query window (last 24h), the vertical constraint, the auth challenge, and the payment method. This is complete given the tool's complexity and rich annotations.

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

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

Schema coverage is 0%, but the description fully compensates by listing all 7 allowed vertical values (tech, finance, news, science, health, young_moms, yoga) and adding the canonical-bucket constraint. This directly aids parameter selection beyond the raw enum in the schema.

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

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

The description clearly states the tool fetches a 'stitched audio briefing' of the top-25 trending articles for a single vertical over the last 24 hours. This specific verb+resource+scope distinguishes it from siblings like get_vertical_landscape and 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?

The description provides clear usage context: it is premium (USDC on Base via x402), the vertical must be one of 7 canonical buckets, and the first call without X-Payment triggers a challenge-retry flow. However, it does not explicitly name alternatives or state when not to use this tool relative to 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?

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by adding context: 'Public — no auth required' and the x402-gated nature of the premium-briefing URL. It also discloses the tool's composite nature and return components, which is valuable behavioral information.

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

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

The description is two sentences with no fluff. The first sentence packs the return contents, the second provides usage context and alternatives. Every word earns its place, making it concise and well-structured.

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

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

With only one parameter, no output schema, and rich annotations, the description covers the essential context: what the tool returns, when to use it, and that it's public. The explicit enumeration of return components compensates for the lack of an output schema.

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

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

The schema already provides 100% coverage for the single 'vertical' parameter with a detailed description of valid slugs. The description adds minimal parameter-specific meaning beyond repeating 'single vertical', so a 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 what the tool does: 'Return everything an agent needs to onboard a listener for a single vertical in one tool call' and explicitly lists the components (top stories, host persona, premium-briefing URL, public RSS feed). It distinguishes itself from sibling tools by describing the one-shot aggregation versus individual calls.

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

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

The description provides explicit usage guidance: 'Use after the agent has decided which vertical to set up' and names the alternative round trip it saves (get_personas, search_articles, get_premium_briefing). This clearly tells the agent when to use this tool instead of others.

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 meaningful context about auth ('Public — no auth required') and what is included in each entry (title, host, vertical, RSS URL, deep-link). It discloses the tool is for listing the public catalog without needing to infer URL patterns. No contradiction with annotations. Slightly more behavioral detail (e.g., response size) would earn a 5, but it is solid.

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

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

The description is well-structured: it states the main function first, then details the catalog contents and fields, then gives usage guidance, and ends with auth note. Every sentence adds value and none are redundant. Although it is a bit longer than the TDQS 4.3 example, every word is informative and it remains 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?

The description fully covers what this no-parameter, no-output-schema tool does. It explains the catalog scope, the hosts, the fields in each entry, how to use the RSS URL, and the auth status. There is no missing information that would prevent an agent from using 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?

The input schema has zero parameters, so the baseline is 4. The description does not need to add parameter semantics because there are none. It correctly focuses on the output and usage instead.

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

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

The description opens with a specific verb and resource: 'Return the public catalog of Storyflo podcast shows'. It clearly enumerates what the catalog contains (Declassified archive plus 6 named daily-brief shows) and differentiates from siblings by noting it avoids re-deriving from /v1/podcasts/* URL patterns. This is a clear, actionable statement of 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?

The description provides explicit guidance: 'Use to surface every audio show an agent can offer its user without re-deriving the catalog from /v1/podcasts/* URL patterns.' It gives a clear scenario and an alternative to avoid. However, it does not name specific sibling tools or state when not to use them, so it falls short of a full 5.

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, and destructiveHint=false, so the safety profile is covered. The description adds context beyond this by specifying that the returned feeds are those the agent minted on the human's behalf, clarifying the exact scope of the data. This is useful behavioral information 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 a single sentence that is front-loaded with the verb 'Return' and directly states the resource. There is zero waste or repetition of the title or annotations. It is as concise as possible while still providing meaningful context.

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?

This is a simple, read-only list operation with no parameters, no output schema, and strong safety annotations. The description fully explains what the tool returns and the specific scope, making it complete for the tool's complexity. There are no gaps in information needed for an agent to select and invoke 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?

The input schema has zero parameters, so there are no parameter descriptions to add. As per the baseline for 0-parameter tools, this scores a 4. The description does not need to discuss parameters because 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?

The description clearly states the tool's function: it returns listener feed(s) that the agent has minted on the human's behalf. The verb 'Return' is synonymous with 'list' and the resource is specific, distinguishing it from sibling tools like list_podcasts. However, the phrase 'listener feed(s)' is somewhat jargon-heavy, slightly reducing 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 no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or compare with sibling tools such as get_my_private_feed or subscribe_topic. The usage is only implied by the tool name and title, not explained.

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

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

Annotations already indicate idempotentHint and non-read-only behavior. The description adds valuable context: it verifies the file is in storage before changing anything and specifies the RSS feed timing effect. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds meaningful detail without redundancy or filler.

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

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

With four params fully described and no output schema, the description explains the process (verification, attachment, RSS feed) and the ownership restriction. It omits failure handling but is reasonably complete for 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?

Input schema covers all parameters with descriptions, including that 'key' comes from publisher_upload_audio. The description adds no additional parameter-specific meaning beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states a specific action: confirming a finished upload, marking an episode live, and attaching one upload to one owned episode. This distinguishes it from sibling tools like publisher_upload_audio (upload vs. attach) and get_* 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 implies the tool is used after an upload is finished, with the outcome happening on the next RSS build. It gives clear context of when to use it, though it does not explicitly name alternatives or say when not to use it.

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

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

Beyond the annotations, the description reveals that recording the connection does not move audio and that scanning happens afterward. This explains the tool's side effects and operational model, adding valuable context that annotations alone don't provide.

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

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

Two dense sentences cover purpose, usage, and 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?

Given the tool's simplicity and the annotations covering safety traits, the description explains the two-step process, the non-destructive nature, and the subsequent scan, making it sufficient for an agent to execute correctly without output schema.

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

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

While the schema already describes each parameter, the description adds crucial usage semantics for the 'folder' parameter: the two-phase invocation pattern ('Call with NO folder argument first... Then call again with folder=...'). It clarifies that the folder is a Drive URL and that omitting it yields setup instructions, going beyond the schema's brief description.

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

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

The description opens with a specific verb ('Connect') and resource ('Google Drive folder of recordings'), and clarifies the intended outcome ('match them to episodes automatically'). It also positions itself in contrast to uploading, which distinguishes it from sibling tools like publisher_upload_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 it's the alternative to uploading a back catalogue file by file, giving a clear when-to-use. Provides step-by-step instructions: first call without folder argument gets setup instructions, then call with folder URL. This leaves no ambiguity about invocation sequence.

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, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by explaining the meaning of 'live' and 'awaiting', and notes that it lists the 'real state' of episodes, which goes beyond what annotations provide.

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

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

The description is two sentences long, front-loaded with the primary action, and every clause adds meaning—order, state definitions, and filtering use case. No filler or 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 there is no output schema, the description does a good job explaining what the tool returns qualitatively (episodes with their states). It also covers the main behavioral nuance (live vs awaiting) and provides a practical use-case example. It doesn't detail output fields, but for a list tool with this scope it's reasonably 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 only 50%, so the description helps compensate by explaining the status enum values ('live' and 'awaiting') and their semantic differences. It does not add meaning for limit or pagination, but the core filtering parameter is clarified, which is valuable.

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 starts with a specific verb and resource: 'List a publisher's episodes', and provides additional scope ('newest-first', real state). This clearly distinguishes it from sibling tools like list_podcasts, publisher_stats, and publisher_status, which address different resources or aspects.

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 usage guidance by showing how to filter with status=live or status=awaiting to answer the question 'what is still pending?'. While it doesn't list alternatives to avoid, the context clearly implies this is the tool for listing episodes with these states, and the sibling list further contextualizes its niche.

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, and destructiveHint=false, establishing this as a safe read operation. The description adds valuable context beyond that: it explains the tool's focus on auto-attach decisions, lists the categories of files reported, and notes that renamed files can be picked up on the next scan. This reveals behavior about what the tool surfaces and how results relate to future scans.

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, somewhat lengthy sentence but front-loads the key idea ('What the connected folder has produced') and provides necessary detail without excessive filler. It could be better structured, but it is effective and not overly verbose.

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

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

With no output schema, the description must convey return value expectations. It does so by naming the categories of results (files seen, matched/attached, non-auto-attached with reasons) and hints at the actionable purpose (renaming files for next scan). While it doesn't specify the exact response format, it is sufficient for an agent to understand what the tool will provide.

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 both parameters (token and tenant_slug) having descriptions. The description adds no additional parameter context, but per the baseline rule, high schema coverage means a 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 the tool reports on the connected folder's production: files seen, matched/attached, and files that could not be auto-attached due to filenames not identifying an episode. This specific verb+resource+scope distinguishes it from sibling tools like publisher_stats or publisher_episodes, which likely cover different 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 gives no explicit guidance on when to use this tool versus alternatives. It implies usage for checking folder status and finding files needing rename, but doesn't state prerequisites, exclusions, 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, idempotentHint, and destructiveHint. The description adds useful context about the default/max window (already in schema) and importantly explains that zero plays on a new feed is normal due to indexing delays, setting expectations for results. 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?

Three concise sentences, each adding value: the core functionality, the use cases, and a caveat about new feeds. No filler, front-loaded with the main 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?

For a read-only stats tool, the description explains the main output (plays and episodes) and covers an edge case (zero plays). It lacks detail on response format, sorting, or pagination, but given the simplicity and good annotations/schema, it is reasonably 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?

The schema documents token and tenant_slug with descriptions, and days has a default/min/max. The description mentions the window defaults but does not add substantive meaning beyond the schema—e.g., it doesn't explain how days affects aggregation or return format. With 67% schema coverage, the description could have compensated more but doesn't.

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 plays over a configurable window and the episodes that drive them. It also frames the tool as answering specific questions ('how did last month go', 'which episode is working'). However, it does not explicitly mention how it differs from sibling tools like publisher_episodes or publisher_status.

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

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

The description provides clear use cases, such as evaluating monthly performance and episode effectiveness, plus a practical note that zero plays is normal for new feeds. It does not explicitly state when to avoid this tool or suggest alternatives, so it lacks explicit exclusion/alternative 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful domain context, such as the feed URL being the one to submit to Apple Podcasts and Spotify, and clarifies what the episode counts mean, going beyond the structured annotation 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?

The description is a single, information-dense sentence followed by concrete usage examples. Every word adds value and there is no redundancy or filler.

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

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

With no output schema, the description adequately enumerates the key return values (feed URL, episode counts, audio state). It could mention edge cases like zero episodes or error conditions, but for the tool's simple scope it is sufficiently 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%, and the schema already thoroughly explains both token and tenant_slug. The description adds no additional parameter-specific information, so a 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 defines the tool as a status overview showing a publisher's feed URL, episode counts, and audio status. It differentiates itself from sibling tools by being the 'first call' status check, as opposed to detailed episode or stats 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?

Concrete example queries ('what is my feed URL', 'is anything stuck') and a recommendation to use it as the first call provide clear usage context. However, it does not explicitly mention when not to use it or name alternative tools for specific needs.

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 goes beyond the limited annotations (all false hints) by stating exactly what happens and what does not: it returns a presigned PUT URL and a curl command, moves no bytes, and mutates nothing in storyflo. This level of side-effect transparency is excellent.

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

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

The description is four well-structured sentences, with the core purpose front-loaded. Every sentence contributes: purpose, when-to-use, return value, and side-effect clarification. 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?

Despite having no output schema, the description explains the return value (presigned PUT URL + curl command) and the complete workflow context (the user must then call publisher_attach_audio). This makes the tool's behavior self-contained and unambiguous.

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

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

The input schema provides 100% parameter descriptions, so the description does not need to repeat them. The description adds a note about audio sources but does not deepen parameter semantics. Baseline 3 is appropriate given full 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?

The description clearly identifies the verb ('Get a one-time upload URL') and the resource ('an episode's source audio'), and it specifies the exact scenario where it is needed ('when an episode shows as awaiting'). It also distinguishes this tool from siblings by explicitly contrasting it with the later publisher_attach_audio step.

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 when-to-use guidance: 'Use this when an episode shows as awaiting.' It also clarifies the workflow boundary: nothing is uploaded until publisher_attach_audio is called, preventing misuse. This effectively differentiates it from the attach step.

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 and idempotentHint, but the description adds valuable context: it is a 'pure pricing-matrix lookup' with no contract creation, and it mentions the returned contact_url as an action item for the human. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, and every sentence adds value: outcomes, side-effect disclaimer, and human handoff. No redundancy or filler.

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

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

With only 2 well-documented parameters, no output schema, and rich annotations, the description fully covers the tool's behavior, return contents, side effects, and auth. It is complete for a simple lookup 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 100%, so both parameters are fully documented in the schema. The description does not add additional semantics beyond what the schema already provides, earning the baseline score of 3.

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

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

The description uses a specific verb 'Return' with the resource 'indicative partnership tier' and details the exact outputs (tier, monthly fee, revenue-share bps). It clearly distinguishes itself from sibling tools, none of which relate to partnership quoting.

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

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

It explicitly states when to use the tool (to get an indicative tier) and provides exclusions: 'no contract is created' and instructs the agent to hand the contact_url to a human. It also clarifies auth requirements ('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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses key behaviors: it returns a human-visited URL, the magic link flow, verification triggers slug/ref_token minting, and it never sends email or creates rows. This adds significant behavioral context.

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

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

The description is dense and front-loaded, with every sentence adding critical information: the URL resolution, the no-side-effect guarantee, and the public access. 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?

For a tool with three params, no output schema, and strong annotations, the description fully covers the return value, side effects, auth, and use case. It is complete for an agent to decide on and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description reinforces how parameters are used (prefilled into the URL) and explains the email magic-link flow. It adds a bit of semantic meaning beyond the schema descriptions, though not much new.

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's purpose: resolving the storyflo embedder onboarding URL prefilled with partner's name, email, and optional vertical. It distinguishes itself from siblings like get_embedder_manifest by focusing on the onboarding URL handoff, not manifest retrieval.

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: it is a discovery + handoff surface for speculative calling, and it explicitly states what the tool does NOT do (no DB row, no email sending, public/no auth). This tells the agent when to use it and when not to expect side effects.

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 idempotentHint=true, so the safety profile is covered. The description adds behavioral value by listing the exact return fields (slug, title, publisher, vertical, snippet, audio_url, listen_seconds) and explaining the vertical scoping behavior, which goes beyond the annotations. However, it does not mention edge cases like empty queries or pagination behavior.

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

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

The description is two sentences, front-loaded with the primary purpose, and every sentence adds value. It efficiently covers the resource, return fields, and vertical scoping without unnecessary fluff.

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 search tool with 3 optional parameters and no output schema, the description is reasonably complete. It specifies the return fields, and the schema provides constraints for limit and query. It does not explain sorting or empty-query behavior, but given the annotations and schema, the context is sufficiently covered for an agent to invoke the tool correctly.

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

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

Schema description coverage is only 33%, with only 'query' having a schema description. The description compensates for 'vertical' by listing allowed values, but 'limit' is not mentioned in either the schema description or the tool description. The parameter semantics are partially clarified, but not fully compensated for the low 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?

The description clearly states the tool's function with a specific verb ('Search') and resource ('Storyflo's article corpus'), and lists the return fields, making the purpose unambiguous. It does not explicitly name sibling tools like search_declassified, but the scope is clear enough to differentiate from other search 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 usage guidance for the vertical parameter ('Use vertical to scope') but does not mention when to use this tool versus alternatives such as search_declassified or get_article. The usage context is implied rather than explicitly stated, and there are no exclusion criteria or alternative tool references.

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, and destructiveHint=false. The description adds behavioral context beyond annotations: it explains the substring matching mechanism, the public/no-auth access, and the source of cases (FBI, CIA, etc.). This enriches the agent's understanding without contradicting any annotation.

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

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

Three sentences, each earning its place: the first states the core purpose, the second explains the matching mechanism, and the third provides usage context and alternative. No redundant phrasing; appropriately sized and front-loaded.

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

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

For a simple search tool with two parameters, no output schema, and strong annotations, the description is complete: it covers what is searched, how matching works, when to use it, the alternative tool, and auth requirements. No missing critical context.

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

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

The input schema covers `query` with a description ('Substring matched against case title + synopsis'), which the description essentially repeats. For `limit`, the schema provides type, default, min, and max, but no explicit semantics; the description also does not explain `limit`. The description does add example topics ('UAP', 'JFK', 'COINTELPRO', 'Roswell') that help understand the query parameter, but it does not compensate for the 50% schema coverage gap on `limit`.

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 identifies the verb ('Search'), the resource ('Storyflo's Declassified archive'), and the specific scope (narrated cases from government documents). It distinguishes itself from the sibling `get_declassified_case` by explicitly stating this tool is for finding cases before fetching the full case. This meets the 'specific verb+resource+scope' criterion and differentiates from siblings.

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

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

The description provides clear guidance on when to use the tool: 'Use when the agent needs to find a Declassified case matching a topic' and explicitly mentions the alternative `get_declassified_case` for fetching the full case. It also notes that no auth is required. It lacks an explicit 'when-not-to-use' but the naming and context make the alternative 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 establish read-only and idempotent behavior. The description adds critical context beyond annotations: results are never blended across corpora, rankings are within-corpus only, profile changes ordering/enrichment, and signals are qualitative with no market odds or investment advice. This is exactly the kind of behavioral nuance that helps an agent reason about outcomes.

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, but each is information-dense and well-organized: first defines function and output structure, second gives usage conditions, third explains profile semantics and critical limitations. Slightly long but no filler; front-loaded with 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 description covers input semantics (query, corpora, profile), output shape (per-corpus buckets), ranking behavior, and limitations. It lacks explicit pagination/error details, but for a search tool with no output schema, the description provides enough to set expectations and avoid misuse. Sibling differentiation is clear.

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

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

Schema covers 80% of parameters with descriptions. The tool description enriches the meaning of `profile` by naming concrete behaviors (desk leads with signals via supporting evidence; publisher leads with news/declassified for citation), and `corpora` is explained as a comma-separated subset. The `vertical` parameter has no description and is not addressed, leaving a gap for a numeric-limited but non-trivial parameter.

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

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

The description opens with 'Search ALL of Storyflo in one call' — a specific verb and resource — and immediately clarifies the unique per-corpus bucketing behavior. It also distinguishes itself from siblings by positioning itself as the unified alternative to corpus-specific searches like search_articles and 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: 'when you do not already know which corpus holds the answer, or when a topic spans several.' This implies the inverse condition (use corpus-specific search when you know the corpus), and it also explains profile-based use cases, offering practical guidance for selecting this tool over 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?

Beyond annotations, the description discloses the SSE endpoint URL behavior, event types, frame shape, the ~1000-event replay on connect, the 30-second heartbeat, and public-anonymous read access. This is rich behavioral context that annotations do not cover.

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

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

The description is compact, well-structured, and front-loaded with the core purpose. Each sentence delivers useful information: client usage, event types, frame shape, replay, heartbeat, and auth.

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 streaming tool with no output schema, the description fully covers return shape, event semantics, connection behavior, and client options. It is self-sufficient and leaves little ambiguity.

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

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

The schema covers both parameters fully with descriptions and an enum for event_type. The description adds that filters are passed as query params, but this is a minor addition since schema coverage is 100%.

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 subscribes to real-time briefing-render events and returns an SSE endpoint URL. It specifies the concrete event types and distinguishes this streaming tool from the sibling getter tools.

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

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

Provides explicit guidance on how to consume the endpoint: 'the agent's MCP client should open it with EventSource (browser), httpx.stream / aiohttp (Python), or curl -N (CLI)'. It does not explicitly contrast with polling or sibling tools, but the real-time subscription use case 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?

The description adds significant behavior beyond annotations: it explicitly states it is read-only, does not store email or PII, requires no auth, and explains what is returned (episodes_url, matched_so_far). This aligns with annotations and enriches them with operational details.

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 three sentences, front-loads the primary purpose, and every sentence adds essential information: what it does, what it returns, and its safety/access profile. No redundant or filler content.

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 2 parameters and no output schema, the description fully covers the return format (episodes_url, matched_so_far), security (no PII), auth (public), and usage context. It is complete and self-contained.

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%, but the description adds crucial meaning by clarifying that the email parameter is not stored and is informational only. This addresses potential privacy concerns beyond the schema's simple 'optional' note, adding value for an agent.

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 resolves a podcast-feed URL for subscribing to automatically receive new Declassified cases, which is a specific verb+resource. It also distinguishes itself from generic subscription tools by explicitly targeting Declassified content and listing compatible podcast apps.

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

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

The description provides clear context for when to use the tool: when a user wants to subscribe to Declassified cases via a podcast feed. It doesn't explicitly name alternatives or exclusions, but the context is sufficient to infer appropriate usage.

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 include idempotentHint and destructiveHint, but the description adds crucial side-effect details: persistent server-side write, idempotency on identical input, full replacement on different input, and stability of the RSS URL. This goes well beyond the structured fields and fully explains behavior.

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') and every sentence adds useful information. It is appropriately concise for a tool with side-effect behavior, and the first sentence front-loads 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 a single parameter, no output schema, and rich behavioral guidance. The description covers when to use, what happens on re-invocation, how to avoid pitfalls, and what the return value is (RSS URL). It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage of the single parameter, including a description ('Replaces (not appends) the listener's current selection.') and enum values. The tool description repeats the valid slugs and the 1–6 constraint but doesn't add new semantics beyond what the schema already states.

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

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

The description states a specific verb ('Mint or update') and resource ('the human's personal Storyflo podcast feed'), making it immediately clear what the tool does. It also distinguishes itself by naming alternatives: 'Do NOT use to FETCH articles or audio — that's 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?

A dedicated 'When to use' section explicitly states when to use the tool ('Use after the agent has been asked to set up audio news...') and what not to use it for. It also instructs to call `list_subscriptions` first to avoid clobbering an existing feed, giving clear contextual guidance.

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