storyflo

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

The description discloses that this is the 'Heaviest action — counts more against the per-agent rate limit', which is critical behavioral information not captured in the annotations. It also reinforces the read-only nature implied by readOnlyHint=true, with no contradictions.

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

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

Two sentences deliver clear functionality, usage context, and rate-limit warning with zero redundancy. Every sentence serves a 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 three simple parameters and no output schema, the description covers the core purpose, parameter semantics, and a behavioral note. It could optionally mention the return format but is not deficient.

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 description maps the three parameters (limit, window, verticals) to natural language ('top-N', 'requested window', 'selected verticals'), but does not explain enums or defaults. Given 0% schema coverage, the description adds moderate semantic value but lacks detail on parameter constraints.

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 'aggregate' and clearly identifies the resource 'top-N articles across selected verticals for the requested window', making the tool's purpose explicit. It also provides an example use case, distinguishing it from sibling tools like search_articles or get_vertical_briefing.

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

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

The description explicitly states when to use this tool ('Use this for 'read me today's tech news' style prompts') and warns about its heavy rate limit cost. While it doesn't list alternative tools for when not to use it, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds rolling window behavior (today/week/month) and clarifies public access. No contradictions. Lacks details on return format or pagination, but annotations cover 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?

Three sentences, front-loaded with action, no fluff. Every sentence adds value: purpose, use case, parameter details, auth status.

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?

Sufficient for a simple tool with 2 params and no output schema. Covers purpose, usage, parameters, auth. Could mention return type (list of cases) but implied. Sibling tools provide 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?

Description explains window parameter options but not limit. Schema provides defaults and constraints for both parameters. With 0% schema description coverage, description compensates partially but not fully (limit undocumented).

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

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

Clearly states 'Return the most-recently-published Declassified cases over a rolling window,' specifying verb and resource. Differentiates from siblings like get_declassified_case (single case) and search_declassified (search) by emphasizing recency and rolling window.

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

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

Explicitly says 'Use for "what's new in Declassified this week" style prompts,' providing clear use context. Also notes 'Public — no auth required.' Does not explicitly list alternatives or when not to use, but context is strong.

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

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

Annotations already declare readOnlyHint and destuctiveHint false. The description adds that it returns 'body_text + audio_url', which is useful beyond the annotations. No contradictions.

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

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

Single sentence of 15 words, front-loaded with purpose and key return fields. 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?

For a simple fetch tool with one required parameter and no output schema, the description covers the return fields (body_text, audio_url). Minor gap: not specifying slug format or potential return codes.

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 0% description coverage and only one parameter 'slug' which is a string. The description says 'by slug' but does not clarify what a slug is or its expected format, leaving ambiguity for the 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 states 'Fetch the full record for an article by slug', clearly specifying the verb (fetch), resource (article), and identification method (by slug). It distinguishes from the sibling 'get_audio_url' which only returns 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?

The description implies usage (fetch by slug) but does not provide explicit when-to-use or when-not-to-use guidance, nor alternatives among many sibling list/search 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 adds valuable behavioral context beyond the annotations: it discloses that the returned URL differs based on user tier (free: stitched-with-ad; plus/pro: bare audio). However, it does not mention error conditions or edge cases (e.g., missing audio), but given the annotations already declare readOnlyHint and idempotentHint, the description improves transparency.

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 no extraneous information. Every word adds value.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers the key differentiator (tier-based output). It could mention the function's idempotency or error handling, but annotations cover idempotency. The description is nearly complete for a straightforward 'get URL' 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 0%, meaning the description must compensate for the undocumented 'slug' parameter. The description only says 'for an article,' leaving the user to infer that slug likely identifies the article. This provides minimal semantic help and does not specify format or source.

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 a playable audio URL for an article. It further distinguishes the output based on user tier (free vs plus/pro), making it specific and 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 implies usage context by mentioning tier-dependent behavior, but it does not explicitly state when to use this tool versus alternatives (e.g., get_article) or if there are prerequisites (e.g., article must have audio). No direct when-not-to-use guidance is provided.

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

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

The description adds operational context beyond the annotations: read-only, idempotent, fail-closed (error when disabled/unconfigured), and attribution-aware with default slug. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description complements rather than repeats these, providing valuable extra 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 well-organized with sections ('Behavior', 'When to use') and uses clear, direct language. While detailed, it avoids unnecessary verbiage. Could be slightly trimmed, but structure aids readability.

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 (affiliate URL generation, fail-closed behavior, attribution) and the absence of an output schema, the description covers essential aspects: error handling, default behavior, and usage context. It provides sufficient completeness for an agent to use 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% (both parameters documented). The description adds extra semantics: for 'asset', it notes case-insensitivity and upper-casing before embedding; for 'embedder_slug', it explains the default fallback to '?ref=storyflo' and the attribution purpose. This additional context goes beyond the basic schema descriptions.

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

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

The description clearly states the tool returns a Kraken affiliate URL for a given crypto asset. It specifies the exact action ('Return') and resource ('Storyflo's markets-partner Kraken affiliate URL'). It distinguishes from siblings by noting it is an editorial linkout, not a trading prompt, and that it is markets-as-INPUT posture.

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

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

Explicit 'When to use' section advises to surface the link in show-notes copy or MCP-client renderings of crypto-relevant stories. It explicitly warns against inlining into spoken audio without a host-read framing line. This clearly delineates appropriate usage from misuse.

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, so the safety profile is clear. The description adds value by listing the exact return fields and explicitly stating 'Public — no auth required,' which supplements 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 primary purpose. Every sentence is informative 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?

The description fully covers the tool's purpose, parameters, return fields, usage context, and authentication status. No output schema exists, but the listed fields suffice for the agent to understand the return value.

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

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

With 100% schema description coverage, the schema already documents the 'slug' parameter. The description adds meaning by specifying that the slug comes from 'search_declassified', which helps the agent understand how to obtain its value.

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 the full record for a Declassified case by slug, listing the specific return fields. It distinguishes from sibling 'search_declassified' by explicitly directing to use after that tool.

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 after search_declassified when the agent needs the full case body to summarize, narrate, or hand off audio playback.' It also notes that no auth is required. However, it does not mention when not to use or compare to alternatives like other get_* 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 and idempotentHint. The description adds valuable context: it's original analysis, not raw market data, requires citation, and is not investment advice. This goes beyond annotations.

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

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

The description is well-structured with a clear lead sentence. It is somewhat verbose but each sentence contributes value. Front-loads purpose effectively.

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 fully explains what each item contains, behavioral constraints, citation requirements, and filtering options. It is complete for an AI agent to understand usage.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description repeats 'Filter by source' but adds no new meaning beyond what the schema already provides.

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 tool as returning the Storyflo Divergence Index, a computed metric. It specifies the resource, scope, and distinguishes it from siblings like get_market_linked_stories by emphasizing it's original analysis, not raw market data.

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

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

The description provides usage context (public, no auth, filtering options) but does not explicitly guide when to use this tool versus alternatives or state when not to use it. No sibling comparisons are mentioned.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds value by stating the tool is public (no auth) and describing the manifest contents. No contradictions.

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

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

Two sentences, no wasted words. First sentence defines the core function; second provides usage guidance and public note. Efficient 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?

For a simple tool (1 param, no output schema), the description covers purpose, when to use, parameter meaning, and access rights. Completely sufficient for agent decision-making.

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?

Single parameter 'slug' with 100% schema coverage. Description adds context that slug identifies the embedder but does not provide additional meaning beyond the schema's example values. 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?

Clear verb ('Get') and resource ('per-embedder agent manifest') with specificity: wraps a public endpoint and returns a JSON bundle of creative formats, voice options, payout config, and beacon URLs. Distinguishes from siblings like register_embedder and 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?

Explicitly states when to use: 'Use after register_embedder or when an agent is reading another partner's manifest to plan an ad buy.' Also notes it is public and requires no auth, providing clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value beyond annotations by stating the tool wraps a public JSON file and requires no authentication, which clarifies its open and safe 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 two sentences: the first explains what the tool does, the second gives usage scenarios. Every word carries weight. It is appropriately concise 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?

Given no parameters, no output schema, and simple nature, the description completely covers the tool's purpose, contents, and usage context. It lists the manifest contents (creative formats, payout rails, etc.) and notes public access.

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 no parameters and schema description coverage is 100%. Per rubric, no parameters set baseline at 4. The description adds no parameter info as none exist, which is acceptable.

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

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

The description clearly states the tool returns the platform-wide embedder network manifest, listing specific contents (creative formats, payout rails, etc.). It distinguishes from the sibling tool get_embedder_manifest by emphasizing 'platform-wide' and 'DSP/SSP onboarding bundle'.

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 two explicit use cases: evaluating whether to wire storyflo into a surface and when a DSP partner needs the canonical integration shape. It also notes the tool is public with no auth required. However, it does not explicitly exclude alternatives, though the use cases are well-targeted.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description explains that this is an editorial surface, not market-data redistribution, and lists what data is returned (qualitative tags, link-out). 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 concise (4 sentences), front-loaded with core purpose, and every sentence adds unique value without redundancy.

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

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

Given no output schema, description fully explains return items (qualitative tags, link-out) and what is excluded (market data). Sufficient for agent decision-making.

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 75%; description adds value by explaining filter options (vertical, category, signal tags) and giving example categories. However, the 'limit' parameter is not discussed, slightly reducing completeness.

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

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

The description clearly states the tool returns Storyflo stories matching actively traded event contracts on Kalshi, with specific verb+resource. It distinguishes from siblings by focusing on market-linked stories, which is unique among the listed 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?

Explicitly says when to use ('when the agent needs to know which Storyflo stories are about news themes that have an actively traded event contract'), provides examples (World Cup, politics), and clarifies what not to expect (no raw prices, probabilities).

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 behavioral context: identity resolution from OAuth token, zeroed output for anonymous callers, and reaffirms 'Read-only, no side effects.' No contradictions.

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

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

The description is four sentences, front-loaded with the main action. Each sentence adds essential information: output summary, identity handling, use cases, and safety. No wasted words.

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

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

With no input parameters and no output schema, the description fully covers what the tool does and what to expect: output fields listed, behavior for anonymous callers explained, and use cases provided. Complete for its 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?

The input schema has zero parameters, so baseline is 4. The description adds value by explaining what the output contains, which helps the agent understand the tool's purpose even without parameters.

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

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

The description clearly states the tool returns the caller's own trailing 30-day MCP tool-usage summary with specific metrics (total calls, success rate, p50 latency, per-tool counts). It distinguishes itself from sibling tools by focusing on MCP usage analytics, which no other tool covers.

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

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

The description explicitly lists three use cases: self-budgeting against rate limits, auditing tool usage, and deciding on paid tiers. It also notes that anonymous callers receive a zeroed shape, guiding 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?

The description adds significant behavioral context beyond the annotations: explains idempotency (token minted on first call and stable), security warning about keeping URL private, and the authentication flow. No contradictions with annotations.

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

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

The description is a single dense paragraph that is well-structured: purpose first, then usage details, then security note. While efficient, it could be slightly more concise by breaking into shorter sentences, but overall it earns its length.

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 complexity of authentication, token stability, and security, and the absence of an output schema, the description covers all essential aspects: what the URL is, how to use it, identity model, security, and behavior across calls. It is fully complete for the tool's purpose.

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

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

Despite 100% schema coverage, the description adds substantial meaning: explains listener_token as identity credential, where to obtain it, and that no OAuth is required. It also clarifies the private feed token behavior, going well beyond the schema description.

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

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

The description clearly states the tool returns the caller's private per-user podcast feed URL, using a specific verb and resource. It distinguishes itself from siblings by emphasizing privacy and personalization, which is unique among the listed 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 clear usage context: paste the URL into a podcast app, pass the listener_token as identity. It explains the authentication model but does not explicitly state when not to use or name alternative tools, which would improve 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by revealing that no authentication is required and listing the specific fields returned (URLs, verticals, etc.), which is beyond what the annotations convey.

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 that efficiently convey purpose, content, usage guidance, and access information. Every word earns its place with no redundancy.

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

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

Given no output schema, the description lists the return fields comprehensively, which is sufficient for an agent to understand the tool's output. No additional context (pagination, limits) is needed for a simple catalog retrieval.

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 baseline score is 4. The description does not need to add parameter info, and it correctly omits it.

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

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

The description specifies the exact resource ('host persona catalog') and the action ('return'), listing the fields included (slug, name, voice_id, etc.). This clearly distinguishes it from sibling tools like get_article or get_audio_url.

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

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

The description explicitly states when to use this tool: 'to pick a voice... before rendering audio or briefing the user.' It also notes that it's public and requires no auth. While it doesn't explicitly exclude alternatives, the sibling tools cover distinct resources, making the context 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 discloses that the tool is public with no auth required, which supplements the existing annotations (readOnlyHint, idempotentHint, etc.). It also details the returned data structure without contradicting any 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 that front-load the purpose and immediately explain the returned data. Every phrase adds value, with zero 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 one optional parameter, no output schema, and strong annotations, the description provides complete context: what is returned, when to use it, and access requirements. No gaps remain for an agent to 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 coverage is 100% with clear enum and default, but the description adds functional context: 'today's snapshot covers the rolling 24h; week + month are reflected back for future expansion.' This clarifies the advisory nature of the window parameter beyond what the schema says.

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

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

The description clearly states it returns a cross-vertical trending snapshot with specific components (top stories, active publishers, daily-brief compilation, per-vertical hot lists). This distinguishes it from sibling tools like get_vertical_briefing or digests by focusing on trending content across verticals.

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 provides use cases: 'when the agent needs to surface what's hot on storyflo right now' or 'decide which vertical landscape to dig into next'. Also states 'Public — no auth required', which guides access expectations.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds critical behavioral context: payment mechanism, time window (24h), and need for X-Payment header. 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 sentences: first states purpose, second states premium nature, third explains payment flow. Front-loaded, no wasted words.

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

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

Covers purpose, parameters, and payment flow thoroughly. Missing explicit description of the response structure after payment (e.g., URL to audio), but the intent is clear given the tool's name and sibling tools.

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?

Only parameter 'vertical' has an enum of 7 values explicitly listed in the description, fully compensating for 0% schema description coverage. Enum values named clearly.

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

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

Clearly specifies verb (Fetch), resource (audio briefing), scope (top-25 articles, last 24h, single vertical). Distinguishes from siblings like get_vertical_landscape and stream_briefing_render_events.

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 explains the premium x402 payment flow with two-step process (challenge then signed retry). Restricts verticals to 7 canonical buckets. Provides clear actionable steps.

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

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

Beyond annotations (readOnlyHint, destruptiveHint=false, idempotentHint), the description discloses what data is returned (top stories, persona, premium URL, RSS), that it's a one-shot call eliminating multiple round trips, and that no authentication is needed. This adds significant behavioral context not captured 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?

Extremely concise at two sentences, with the main purpose front-loaded. Every sentence adds value: listing return items, usage context, and authentication status. No redundancy.

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

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

Given the tool's simplicity (single parameter, no output schema) and rich annotations, the description fully covers what the tool does, what it returns, when to use it, and its public nature. No missing information for an agent to correctly invoke it.

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

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

Schema coverage is 100% and the parameter description lists valid values. The tool description does not add new semantic information beyond what the schema already provides; hence 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 states the tool returns 'everything an agent needs to onboard a listener for a single vertical' and lists specific items (top stories, host persona, premium briefing URL, RSS feed). This distinguishes it from sibling tools like get_personas, search_articles, and get_premium_briefing.

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

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

Explicitly tells when to use: 'Use after the agent has decided which vertical to set up'. Also explains benefits: 'saves a follow-up round trip'. Additionally, states 'Public — no auth required' to set expectations.

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 'Public — no auth required,' which provides useful context beyond annotations about access requirements. It does not contradict 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 long, front-loaded with the core purpose, lists specific shows and entry contents, and ends with usage guidance. Every sentence adds value with no redundancy or verbosity.

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 fully explains the return format (title, host, vertical, RSS URL, deep-link), indicates it is public and requires no auth, and covers the intended usage. The tool is simple (no params, read-only), and the description is complete for the agent's needs.

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 100% schema description coverage, so there is no need for parameter details. The description is clear about the absence of parameters, and the baseline expectation is met.

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 specific verbs like 'Return the public catalog' and clearly identifies the resource (Storyflo podcast shows). It lists the specific shows included and what each entry contains, making the tool's purpose unambiguous. This differentiates it from siblings like digest or 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 states 'Use to surface every audio show an agent can offer its user' and explicitly warns against re-deriving the catalog from URL patterns. While it provides clear context and rationale, it does not explicitly name alternative tools for different 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds context that subscriptions are minted on behalf of the human, clarifying scope.

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

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

Single sentence of 15 words, front-loaded with action and object, no extraneous information.

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

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

Description fully covers all necessary information for a zero-parameter, read-only tool with no 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?

No parameters; schema coverage is 100% (trivial). Description explains purpose without needing parameter details.

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

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

Description clearly states it returns listener feeds minted on the human's behalf. Verb 'return' and object 'listener feed(s)' are specific. No sibling with similar 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?

No explicit when/when-not guidance. However, the tool is self-explanatory and siblings do not overlap significantly.

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 false, destructive false, idempotent true), the description discloses verification before mutation, the RSS feed impact on the next build, and the one-to-one ownership constraint. This adds substantial 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 three sentences, each serving a distinct purpose: the action, the verification mechanism, and the scope. No redundancy or 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?

The description covers purpose, prerequisites, effects, and constraints. It lacks explicit return value or error behavior, but for a mutation tool with no output schema, the provided context is sufficient for an agent to select and invoke the tool.

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

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

The input schema already provides descriptions for all 4 parameters, including referencing publisher_upload_audio for the key. The description adds the one-to-one constraint but does not provide additional parameter-level detail beyond what the schema covers.

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 confirms a finished upload and attaches it to an episode, making it live. It distinguishes from sibling publisher_upload_audio by specifying the attach step and the RSS feed effect.

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

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

The description implies usage after upload via the key reference and 'Confirm a finished upload'. It does not explicitly name alternatives, but the context is clear enough for an agent to infer the correct 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?

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: 'Recording the connection moves no audio; the scan happens afterwards.' This clarifies that the tool only records the connection and does not perform an upload or migration, significantly enhancing transparency.

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

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

The description is concise and front-loaded, with the first sentence stating the core purpose, followed by clear setup instructions and a brief safety note. Every sentence earns its place, and the three-sentence structure is easy to parse.

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 two-step tool with no output schema, the description covers the complete interaction model: what the tool does, how to initiate setup, what information to expect (the address to share the folder with), and the follow-up call with the folder argument. It also addresses the non-destructive nature and subsequent scan behavior, making it fully 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?

The schema already describes all three parameters with 100% coverage, including the folder parameter's 'Omit to get setup instructions' behavior. The description reinforces this by explaining the two-step calling pattern and gives a concrete example (folder=<the Drive URL>), but it doesn't add substantial new parameter-level semantics beyond what the schema provides.

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 connects a Google Drive folder of recordings for automatic episode matching, using a specific verb ('Connect') and resource ('Google Drive folder'). It distinguishes from siblings by explicitly framing this as the alternative to uploading files one by one, unambiguously differentiating it from 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?

The description provides explicit when-to-use guidance: it is the alternative to uploading a back catalogue file by file. It also gives step-by-step usage instructions, including calling with no folder argument first for setup instructions and then calling again with the Drive URL, making the workflow unmistakable.

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 the description adds behavioral depth by explaining the meaning of 'live' and 'awaiting' states and the ordering ('newest-first'). This goes beyond the annotations, though it doesn't cover all potential behaviors like pagination.

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 clause adds value (ordering, state meanings, filter usage). 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?

For a read-only list tool, the description covers purpose, state semantics, and a practical use case. It omits response format or pagination details, but the schema's limit parameter and annotation hints mitigate this. Complete enough for basic usage.

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

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

Schema description coverage is 50%, and the description significantly enhances the 'status' parameter by explaining its values and filter use case. It doesn't add detail for limit or token, but the schema already provides constraints for limit and descriptions for token/tenant_slug.

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

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

The description clearly states the action ('List a publisher's episodes') with a specific scope ('newest-first') and distinguishes the tool by explaining the 'real state' concept with specific values. This differentiates it from sibling publisher tools like upload/attach/stats.

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

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

Provides a concrete use case: 'Filter with status=live or status=awaiting to answer what is still pending?' This offers clear context for when to use the tool, but it doesn't explicitly name alternatives or exclusions, 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 and destructiveHint false, providing the safety profile. The description adds valuable behavioral context beyond these: it explains that the tool reports on scan results, lists why certain files were not auto-attached, and notes that renamed files will be picked up on the next scan. This gives the agent a clear picture of the tool's operational behavior without contradicting 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 main purpose and including the most useful detail (un-attachable files with reasons) without extraneous content. Every clause earns its place, making it an excellent example of conciseness for a simple status tool.

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 (2 required parameters, no output schema, clear annotations), the description adequately explains the return content, including the types of file statuses and the actionable purpose (renaming for next scan). It does not provide exact response format, but that is beyond the needed context for agent 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?

The input schema provides full descriptions for both parameters (tenant_slug and token), giving 100% schema description coverage. The tool description itself does not add parameter-specific information, so the baseline of 3 applies: the schema sufficiently documents parameters, and the description does not need to repeat or enhance it.

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

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

The description uses a specific and informative phrasing: 'What the connected folder has produced' followed by concrete output categories (files seen, matched, attached, and un-attachable files with reasons). This clearly differentiates it from sibling status tools like publisher_stats or publisher_status by focusing specifically on the connected folder's file processing outcomes.

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

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

The description implies when to use the tool: to review files that the connected folder has processed, especially those that were not auto-attached due to unclear filenames. However, it does not explicitly state when not to use it or mention alternatives, such as publisher_stats for different metrics, leaving the guidance only implied.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: the default/max window, the inclusion of driving episodes, and the normal expectation of zero plays for newly indexed feeds. No contradiction with annotations.

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

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

The description is only three sentences, front-loaded with the core behavior, then usage context, then a caveat. Each sentence earns its place. The first sentence is slightly ambiguous ('Plays over a window...') but overall it is 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 no output schema, the description should convey return semantics, and it does: plays over a window plus episodes. It also provides default/max values and a real-world caveat. The main gap is a more explicit return shape or field list, but for a read-only stats tool the description 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?

Schema descriptions cover tenant_slug and token, while the days parameter lacks a description. The tool description helps by explaining the window default and maximum, which maps to days. This partially compensates for the missing schema description but does not add detail about token or slug.

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 conveys that the tool returns play counts over a configurable window (default 30 days, max 365) plus the episodes driving those plays. It lacks an explicit imperative verb like 'retrieves' or 'lists,' but the meaning is clear from the title and description, and it is distinct 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 explicitly states what questions the tool answers ('how did last month go' and 'which episode is working') and provides a practical caveat about zero plays on new feeds. It does not name alternative tools or exclusions, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds context about the response content (feed URL, episode counts) but doesn't disclose additional behavioral traits like rate limits, auth specifics, or edge cases. It doesn't contradict 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 three sentences, front-loaded with the primary purpose ('Where a publisher stands right now'), and each sentence adds value: the data returned and the use cases. No fluff 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?

For a simple read-only status tool with two parameters and no output schema, the description covers the key information: what data is returned and when to use it. It could mention the response format or error handling, but for this scope it's 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?

Both parameters (tenant_slug and token) have full descriptions in the input schema, covering 100% of parameter semantics. The description does not add any additional parameter-specific detail, which is acceptable since the schema already provides sufficient guidance.

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 tool as a status overview for publishers, specifying exactly what data it returns (RSS feed URL, episode counts, audio status). It differentiates from sibling tools like publisher_episodes or publisher_stats by listing the specific fields and providing example use cases like 'what is my feed URL' and 'is anything stuck'.

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 this tool: for 'what is my feed URL', 'is anything stuck', or as the first call when a publisher asks how things are going. It doesn't explicitly name alternatives or when-not-to-use, but the usage context is clear enough for an agent to select this over similar publisher 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 annotation readOnlyHint=false contradicts the description's claim that 'this tool alone moves no bytes and mutates nothing'. This is a direct contradiction, so transparency scores 1 despite useful context about the upload flow.

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, front-loaded with purpose, followed by usage and behavioral context. Every sentence adds value.

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

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

Covers purpose, trigger condition, return value (presigned PUT URL and curl command), and the required follow-up call. Lacks detail about how episode_slug is determined since it's optional, but overall adequate for a multi-step tool.

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

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

Schema coverage is 100%, so parameters are described in schema. The description adds no additional syntax or semantics beyond noting the use case (StreamYard, Riverside, Zoom), so it meets the baseline 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?

Description clearly states the tool's function: 'Get a one-time upload URL for an episode's source audio'. It specifies the resource and differentiates from siblings by noting it 'moves no bytes' and is followed by publisher_attach_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?

Provides explicit usage condition: 'Use this when an episode shows as awaiting'. It also explains the follow-up workflow (upload then call publisher_attach_audio), giving clear context. However, it doesn't mention alternative tools for other scenarios, but the awaiting trigger is specific.

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 value beyond annotations by stating the tool is public with no auth required, returns specific data (tier, fee, bps, contact_url), and is a pure lookup. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and there is no contradiction.

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

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

The description is three sentences with front-loaded output specifics, efficient and without unnecessary words. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the return values (tier, fee, bps, contact_url) and the tool's safe, non-destructive nature. With annotations covering safety, the description is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not elaborate on parameter meaning beyond the schema, but schema descriptions for 'vertical' and 'monthly_impressions' are already provided. Baseline score 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 verb 'Return' and the resource 'indicative partnership tier', listing specific outputs (starter/growth/scale/enterprise, monthly fee, bps). It distinguishes the tool from siblings, most of which are get/search/subscribe operations, by emphasizing it is a pure pricing-matrix lookup.

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 outlines when to use the tool (when a partner needs an indicative tier) and what not to do (no contract created, agent should pass contact_url to human). Although it does not explicitly name an alternative tool for formal partnership creation, the guidance on next steps 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?

Discloses all behavioral traits beyond annotations: no DB write, no email sent, returns a URL for human visit, and describes the signup flow. Annotations already indicate readOnly and idempotent; description adds speculative-call safety.

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, focused and efficient. First sentence states purpose, second explains what it does and doesn't do, third adds public/no-auth context. 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 no output schema, the description clearly states the return is a URL. Covers safety, idempotency, and auth requirements. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description reinforces that the URL is prefilled with name, email, and optional vertical, and clarifies the email's role (magic link). Adds meaningful context but schema already covers basics.

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 specifies the exact action (resolve URL) and resource (embedder onboarding URL) with details on what it contains (prefilled with name, email, optional vertical). It clearly distinguishes from sibling tools, none of which generate onboarding URLs.

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

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

Explicitly states when to use (discovery/handoff for onboarding) and when not (it does not create DB rows or send emails). Provides use case context: agents can call speculatively without 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds useful behavioral detail by specifying the exact fields returned and the vertical scoping option. It does not contradict annotations and provides meaningful context beyond them.

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

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

Two sentences: first states purpose and lists return fields, second provides vertical guidance. No wasted words, information is front-loaded, and every sentence earns its place.

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

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

The description covers the return fields and one parameter hint, but lacks details on query matching behavior, limit functionality, or pagination. Given the complexity (3 params, many siblings), more context would help an agent decide correctly, though the basic purpose 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 description coverage is only 33% (only query has a description). The description mentions vertical scoping and its enum values, which are already in the schema. It does not elaborate on the query parameter (e.g., syntax, supported operators) or the limit parameter (e.g., default, interpretation). With low coverage, the description should compensate but adds little.

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

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

The description clearly states the tool searches Storyflo's article corpus and enumerates the return fields (slug, title, publisher, vertical, snippet, audio_url, listen_seconds). This provides a specific verb ('Search') and resource ('article corpus'), and distinguishes it implicitly from siblings like get_article by focusing on search and listing multiple fields.

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 one usage hint: 'Use vertical to scope' with the allowed values. However, it does not explain when to prefer this tool over siblings like search_declassified, get_article, or get_trending_topics. No when-not-to-use or alternative suggestions are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context on substring matching across title+synopsis and confirms public access, but doesn't contradict 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 sentences with no wasted words: purpose, method, usage guidance, and access rights are all front-loaded and efficiently stated.

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 2 parameters and no output schema, the description covers purpose, matching logic, usage sequence, and access; could mention return format but not essential for a search tool.

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

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

The description adds no additional meaning for the 'limit' parameter beyond what the schema provides (default, max, min), and the schema coverage is 50%. The 'query' parameter description in schema is fully repeated.

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 'Search Storyflo's Declassified archive' with a specific verb and resource, and distinguishes itself from the sibling tool 'get_declassified_case' by indicating this is for searching before fetching the full 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?

Explicitly provides when to use ('Use when the agent needs to find a Declassified case matching a topic...') and after use guidance ('before fetching the full case via get_declassified_case'), with an alternative tool named.

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 readOnly/idempotent annotations, the description discloses that results are never blended across corpora, are ranked within each corpus, and that profile changes ordering/enrichment—plus the qualitative-only nature of signals. This adds meaningful 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 a single, well-organized paragraph that front-loads purpose ('Search ALL of Storyflo') and packs each sentence with distinct information—corpora definitions, use case, ranking behavior, profile effects, and caveat.

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 search with no output schema, it explains result structure (per-corpus buckets), ranking, profile impact, and the qualitative limitation of signals. The only significant gap is the undocumented 'vertical' parameter.

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 already covers 4 of 5 parameters with descriptions; the description adds semantic value for 'profile' (desk vs publisher) and explains corpora buckets, though 'vertical' remains undocumented.

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

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

Explicitly states 'Search ALL of Storyflo in one call' and names the three corpora (news, declassified, signals), distinguishing it from sibling search tools by the unified scope and per-corpus bucketing.

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 this when you do not already know which corpus holds the answer, or when a topic spans several,' clearly indicating when the unified search is appropriate over narrower 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?

Adds significant behavioral details: replay of last ~1000 events, 30s heartbeat, public-anon access, event frame shape. This complements annotations (readOnly, openWorld, idempotent) well.

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

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

Front-loaded with purpose, then usage instructions, then event details. Slightly verbose but well-structured for an SSE tool.

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 specifies event types, frame shape, replay behavior, and heartbeat, leaving no ambiguity for agent invocation.

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

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

Schema covers 100% of parameters with descriptions and enums. Description mentions filters as query params but does not add extra meaning beyond schema.

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

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

Clearly states 'Subscribe to real-time briefing-render events' and describes the SSE endpoint purpose. Distinguishes from sibling tools as the only streaming subscription tool.

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?

Identifies when to use (real-time monitoring) and provides client examples (EventSource, httpx.stream, curl -N). No explicit when-not-to but context is clear given sibling tools are mostly read endpoints.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint are false. The description adds value by explaining the specific behavior: it returns episodes_url and matched_so_far, does not store email/PII, and requires no auth. This goes beyond annotations and accurately reflects the tool's behavior with no contradictions.

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

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

The description is concise (four sentences) with a clear front-loaded main action. Every sentence contributes essential information: main action, returned data, read-only nature, and auth requirement. 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 low complexity (2 parameters, no output schema), the description fully covers what the tool does, what it returns, and its behavior. It explains the output components (feed URL, episodes_url, matched_so_far) and clarifies that it is read-only and public. Complete for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds that the email parameter is 'informational only; no row is written for it,' which is already implied by the schema description. This adds minimal new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly specifies the verb ('resolve') and the resource ('podcast-feed URL') for Declassified cases. It distinguishes from siblings like 'subscribe_topic' by focusing on Declassified content and detailing output components (feed URL, episodes_url, matched_so_far).

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 states when to use this tool (for RSS subscription to Declassified cases) and clarifies that it is read-only, public, and does not store PII. It does not explicitly mention when not to use it or alternatives, but the context is clear enough for an agent.

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

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

The description details persistent side-effect, idempotency on identical input, replacement behavior on different input, and single feed per listener. Annotations provide idempotentHint=true but the description adds critical nuance about overwriting vs. appending, which is beyond annotations.

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

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

The description is well-structured with clear sections (purpose, behavior, when to use). It is somewhat lengthy but every sentence adds value. Front-loading the main purpose is effective.

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 side-effect nature and transformation behavior, the description covers all essential aspects: what it does, how it behaves under different inputs, how to avoid common mistakes, and when to use it. No output schema but the return value (RSS URL) is mentioned. Completeness is high.

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%, with the property description already explaining the array of enum slugs, min/max, uniqueItems, and replacement semantics. The tool description reiterates this but adds no new parameter-specific insight. Baseline 3 is appropriate.

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

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

The description clearly states the tool 'mint[s] or update[s] the human's personal Storyflo podcast feed', specifying verb and resource. It distinguishes from siblings by warning not to use for fetching articles/audio. This is a specific, actionable 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?

Explicit 'When to use' section advises using after setting up audio news and not for fetching articles/audio, pointing to alternatives. It also recommends calling list_subscriptions first to avoid clobbering an existing feed. This is comprehensive guidance.

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