Listen Notes

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

Annotations already declare read-only, idempotent, non-destructive. Description adds crucial context: return structure (score, confidence, signals, raw_response per model), cost implications for Anthropic, and default model. 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?

Four sentences, no fluff. Front-loaded with purpose and output. Information is well-organized: action, models, return, use cases. 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 4 parameters and no output schema, the description covers return format, use cases, and cost. Lacks error handling or limitations but is sufficient for agent decision-making. Differentiates well from siblings.

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 good descriptions. Description adds value by explaining default model behavior and the role of '_apiKey' for Anthropic. Exceeds baseline of 3 by providing usage context 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 the action (probe LLMs), the resource (business/brand/product/topic), and output (0-100 score per model). Distinguishes from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on LLM knowledge. Mentions specific use cases.

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

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

Explicit use cases provided (AI-marketing audits, pre-launch brand checks, competitive monitoring). Notes free default model and optional Anthropic with BYO key. Does not explicitly state when not to use, but context is clear enough.

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 useful context beyond those: it routes internally, returns stable pipeworx:// citation URIs, works on every tier, and is one fast call. It does not discuss failure handling or limits, but covers the core behavior 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 the key directive 'PREFER OVER WEB SEARCH' and followed by clear categories. Some repetition ('START HERE', 'default entry point', 'works on every tier') adds length but no new information. However, every sentence serves a purpose, and examples strengthen clarity. Slightly verbose, but well-organized.

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 routing tool with no output schema, this is remarkably complete: it describes the return format (structured answer with citations), the scope of data sources, the trigger phrases, and explicit escape hatches to sibling tools. It even addresses the free-account tier. This gives an agent enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the same question string. The description adds no parameter-specific semantics beyond saying it 'fills arguments' internally, which is about tool routing rather than parameter format. Baseline 3 applies since the schema already documents everything.

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?

Specifically names the action (routes a question to the correct tool, fills arguments) and resource (5,529 tools across 1,455 verified sources). Clearly distinguishes itself from siblings by explicit comparison to ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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

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

Gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists concrete trigger phrases and domains, and names alternatives with specific conditions ('Step up only when needed: ... use ask_pipeworx_grounded; for broad/multi-part use deep_research'). Also clarifies how it handles breaking news.

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 the experimental status, live candidate routing improvements, the current absence of an active candidate, and the fact that it is a full working router with no fallback. This goes well beyond the annotations' read-only/idempotent hints, adding valuable context about the tool's state and potential variability.

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 tight, front-loaded paragraph of three sentences. Each sentence provides distinct information: identity, current status, and usage guidance, with no redundancy or filler.

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

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

For a beta router with no output schema, the description covers the essential context: what it does, how it differs from the stable version, when to use it, and its current operational state. The reference to 'same response shape' and 'use it exactly like ask_pipeworx' makes it sufficient for an agent to invoke 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?

No parameter details are covered in the description, but schema coverage is 100% with all six alias parameters fully described. Since the schema already provides complete parameter semantics, the description adds no extra value, warranting the baseline score.

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 'Beta version of ask_pipeworx' and explains it is an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx by highlighting the experimental routing improvements and the current match to the stable version.

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

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

It explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also contrasts with the stable router by mentioning results are compared against it, implying the stable alternative for non-experimental use.

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

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

The description richly details behavior beyond annotations: it explains that the answer is extracted ONLY from the tool result, lists specific refusal reasons (not_in_source, no_tool_match, etc.), and discloses the cost of an extra LLM call. This complements the readOnly/idempotent annotations without contradiction.

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

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

The description is longer than typical but every sentence carries meaningful information: purpose, mechanism, return format, refusal reasons, usage guidance, cost trade-off. It is well-structured and front-loaded with the core value proposition, though slightly dense.

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 specifies the return contract: {answer, evidence, confidence, source, fetched_at, refusal_reason} and enumerates all possible refusal_reason values. It covers use cases, cost, and when to avoid, making it complete for high-stakes grounded queries.

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?

Since schema description coverage is 100%, all parameters already have clear descriptions (question and its aliases). The tool description does not add new parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('ask') and resource ('Pipeworx'), and describes its core behavior: routing to tools, fetching data, and extracting grounded answers. It also explicitly distinguishes itself from the sibling tool ask_pipeworx by highlighting the hallucination-resistant mode and extra LLM call, making differentiation clear.

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

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

The description provides explicit guidance on when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative: 'prefer ask_pipeworx for casual lookups,' which clearly communicates the trade-off.

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, so the description adds value by specifying the return fields (title, publisher, image URL, Listen Notes id). 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?

Two sentences with efficient structure: main action first, then optional filters, then return fields. 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 presence of an output schema covering return values and annotations covering safety, the description provides a solid overview. Minor gap: no explanation of the 'page' parameter or possible values for sort/region, but overall adequate for a simple list-fetch 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?

With 0% schema description coverage, the description partially compensates by naming three filter parameters (genre_id, region, sort) and their purpose. However, the 'page' parameter is not mentioned, and no value constraints or examples for sort/region are given, reducing clarity.

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

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

The description clearly states the tool's purpose with a specific verb ('Fetch') and resource ('Listen Notes curated list of top podcasts'), and distinguishes it from sibling tools like search or podcast by emphasizing the curated nature.

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

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

The description mentions optional filters but provides no guidance on when to use this tool versus alternatives (e.g., search for broader queries). Usage context is implied but no exclusions or when-not scenarios.

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

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

The description goes well beyond annotations by detailing resolution logic, classification fan-outs, response shapes, resolver contract, parent event extraction, news fallback behavior, safety checks for low-confidence and closed markets, and resolution-rule risk. Annotations already indicate read-only, open-world, idempotent, and non-destructive, and the description adds rich behavioral context without contradiction.

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

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

The description is long but well-structured with clear sections and key terms highlighted. The first sentence front-loads the purpose. Given the tool's complexity, the length is justified, though it could be slightly more concise.

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

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

Despite lacking an output schema, the description thoroughly explains response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and resolution-rule risk. It covers all critical aspects an agent needs to correctly invoke and interpret results.

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

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

With 100% schema coverage, the schema already documents each parameter. The description adds value by explaining the 'market' parameter input types, 'depth' enum meaning, and 'include_raw' boolean context (summary vs full payloads). This enhances understanding beyond schema alone.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like deep_research or polymarket_edges.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive context but does not explicitly exclude scenarios or compare to specific sibling tools, though the detailed fan-out examples imply when it is appropriate.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description aligns perfectly and adds valuable context like fiscal year handling for companies and sorted results. 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 fairly concise with about 4 sentences, each adding value. It front-loads with usage examples. Could be slightly tighter, but 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?

For a tool with simple parameters, no output schema, and clear annotations, the description covers all necessary aspects: what data is returned, how results are sorted, and citation URIs. It is complete for the use case.

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

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

Schema coverage is 100%, and the description significantly enriches parameter meaning. It explains what each type pulls (company financials from SEC EDGAR, drug data from FAERS) and specifies the required format for values (tickers/CIKs for company, names for drug).

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 does side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific verb phrases and distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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 advises to ALWAYS PREFER this tool over sequential single-pack lookups and gives example trigger phrases. It provides good context but does not explicitly state when not to use it, though that is 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?

Beyond the readOnly/openWorld/idempotent annotations, the description richly discloses behavior: it mentions account tiers, depth-specific hops and gap recovery, time expectations (15-60s), return format (verbatim evidence, confidence, source, fetched_at, citation), and guarantees (never invents, citations are fetchable, semantic excerpting). It adds substantial context without contradicting any annotation.

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

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

The description is long but every sentence delivers essential information: purpose, alternatives, limitations, parameter nuance, and behavioral guarantees. It is front-loaded with the critical account requirement and structured so that the agent encounters the most decision-relevant facts first. No fluff or repetition is present.

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 the absence of an output schema, the description fully specifies the tool's return contract (findings packet, gaps[], contradictions[], hop field, resolvable citation_uri) and covers prerequisites, timing, and edge cases. It leaves no significant ambiguity about when or how to 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?

Though the input schema already describes the two parameters, the description deepens understanding by explaining how 'depth' values (quick/standard/thorough) map to facet counts, gap recovery, contradictions scan, and paid tier requirements. It also clarifies that 'question' should be broad/multi-part, adding practical semantic value beyond the schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'Decomposes your question into focused facets' and returns a structured findings packet. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its unique role unmistakable.

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

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

The description gives explicit guidance: 'Best for broad/multi-part questions over structured data', with direct alternatives provided for other use cases ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also specifies the account requirement and when to fall back to ask_pipeworx, providing clear decision criteria.

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 context beyond annotations by stating it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This clarifies the read-only, idempotent behavior already indicated by 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 somewhat long but well-structured: starts with purpose, gives examples, explains output, and ends with usage guidance. Every sentence adds value, though some redundancy could be trimmed.

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 (no output schema, high schema coverage), the description fully explains what it does, what it returns, and when to use it. No gaps are apparent.

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?

All 6 parameters are fully described in the schema (100% coverage). The description only mentions that q, task, search, description are aliases for query, which is also in the schema descriptions. It adds no new semantic meaning beyond what the schema provides, 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 starts with a clear action 'Find tools by describing the data or task' and provides specific domain examples (SEC filings, financials, etc.). It differentiates from sibling tools like search and deep_research by stating it returns the option set with schemas and should be called first when exploring available 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 when to use ('when you need to browse, search, look up, or discover') and when to call first ('when you have many tools and want to see the option set'). It implies that for a single direct answer, other tools might be preferred, but does not name specific alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: it details the multi-source fan-out behavior (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes expected return fields with examples, and discloses a known soft-failure for patents. 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 front-loaded with query examples, then provides a concise overview, and uses clear structure (lists return fields). Every sentence adds value, though the description is somewhat long. Overall well-organized and efficient.

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

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

Given the complexity of the tool (multiple data sources) and absence of an output schema, the description is remarkably complete. It enumerates all key return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), notes limitations (patents soft-fail), and provides usage constraints. No gaps are apparent.

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

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

Schema description coverage is 100% for both parameters (type and value). The description reinforces the schema information and adds minor additional context (e.g., use resolve_entity for names). Since the schema already provides clear semantics, the description adds limited extra value, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose as generating a full cross-source profile of a US public company, with specific examples ('Tell me about X', 'company profile for Microsoft'). It distinguishes from siblings by explicitly recommending this tool over chaining individual lookups and directing users to resolve_entity if they only have a name.

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

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

The description provides explicit guidance on when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use it (names not supported) and directs to the sibling tool resolve_entity as an alternative.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which cover safety and side effects. The description adds value by specifying exactly what data is returned (title, description, audio URL, duration, publish date, parent podcast info), which goes 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?

The description is two sentences: the first front-loads the action and resource, the second lists returned fields. Every word is informative, 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?

Given the tool's simplicity (single parameter, read-only, has output schema), the description is complete. It covers what the tool returns and how to identify the episode. The output schema presumably documents the return structure, so no further detail needed.

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

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

The single parameter 'id' has no schema description (0% coverage), but the description clarifies it is a 'Listen Notes id', adding meaning beyond the type 'string'. The example provides a concrete format, aiding correct usage. Still, more detail (e.g., format) would improve.

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

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

The description clearly states the verb 'Fetch' and the resource 'full details for a single podcast episode', specifying the identifier type 'Listen Notes id' and listing the returned fields. This clearly distinguishes it from sibling tools like 'podcast' (for podcast-level details) and 'search' (for finding episodes).

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 by stating it fetches details for a single episode given an id, which is straightforward. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'search' to find episodes, 'recommendations_for_episode' for related content), but the context is clear enough for an agent to infer.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and pairs with related tools, 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?

Two sentences, action first, no wasted words. Efficient 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?

Complete for a simple destructive tool with one parameter and good annotations. Includes purpose, usage guidelines, and sibling references.

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 100% with clear property description. Description does not add extra info about the 'key' parameter beyond what's in 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?

Clear verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings by mentioning 'pair with remember and recall'.

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 conditions: stale context, task done, clear sensitive data. Implicitly contrasts with remember/recall but no explicit when-not.

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?

Description adds behavioral details beyond annotations: fetches page, extracts title/description/key links, emits standard markdown, output is single text blob. 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?

Single well-structured paragraph with front-loaded purpose, then details, then usage examples. 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 output format and use cases. Missing error handling or edge cases, but given simplicity and rich annotations, sufficiently complete.

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

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

Schema has 100% coverage with descriptions. Description does not add further meaning to parameters, especially max_links. Baseline 3 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?

Clearly states verb 'generate', resource 'llms.txt', and purpose for AI crawlers. Distinguishes from sibling tools by specific output format and use 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 lists three use cases (client site indexing, personal project, competitor audit). However, no mention of when not to use or comparison with sibling tools like scan_competitor_ai_presence.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the return content (genre id and name), which is consistent and non-contradictory.

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

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

Two sentences, front-loaded with the core action, no wasted words. 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?

Given no parameters, rich annotations, and an output schema, the description fully covers what the tool does and how its output should be used, leaving no gaps.

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 are present, so schema coverage is 100% by default. The description does not need to add parameter details, but baseline of 4 is appropriate for zero-parameter tools.

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 full list of genre categories with id and name. It distinguishes itself from sibling tools by focusing on a simple list, unlike more complex tools like best_podcasts or search.

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

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

Explicitly tells agents to use genre_id values to filter best_podcasts or search, providing clear when-to-use guidance for the output.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds that it lists only active subscriptions by default and enumerates the return fields, which adds behavioral context beyond annotations. No contradictions.

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

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

Two sentences with no wasted words. First sentence states purpose and output fields; second sentence gives usage guidance. Front-loaded and efficient.

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

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

For a simple list tool with one optional param, no output schema, and clear annotations, the description fully covers purpose, when to use, return fields, and default behavior. Complete and self-sufficient.

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

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

Schema description coverage is 100% for the single boolean parameter 'include_inactive'. The tool description does not add extra meaning, so 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?

Description clearly states the verb 'List', the resource 'the caller's active subscriptions', and the specific return fields. Distinguishes from siblings like subscribe and unsubscribe because it's strictly read-only listing.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This guides the agent on when to invoke this tool versus alternatives.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses rate limiting (5 per identifier per day), cost implications (free, no tool-call quota), the claim_token workflow, and the fact that the team reads digests daily with roadmap impact — all significant behavioral context beyond the structured fields.

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?

Though longer than typical descriptions, every sentence earns its place: purpose, use cases, exclusion, message format guidance, claim_token workflow, and policy constraints. It front-loads the primary purpose and maintains a logical flow 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 the tool has no output schema and all annotation hints are false, the description fully compensates by explaining the returned claim_token, how to later check status, rate limits, and the tool's scope. No critical operational detail is missing for an agent to invoke and interpret results 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 descriptions cover 100% of parameters, setting a baseline of 3. The description adds meaningful guidance: explaining how to use claim_token to retrieve earlier feedback, and instructing users not to paste end-user prompts but describe issues in terms of Pipeworx tools/packs. This enriches parameter semantics beyond the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from siblings like ask_pipeworx by focusing on feedback about the tools themselves, and enumerates concrete use cases (bug, feature, data_gap, praise).

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 when-to-use guidance (bug, feature, data_gap, praise) and a clear exclusion: if the tool came from a different MCP server, file it there instead. It also offers a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists'), which fully guides agent decision-making.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds info on data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and what is returned (pack, tool, count). 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?

Every sentence adds value: purpose, use cases, data derivation, caching. Well front-loaded with the core function. No wasted words.

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

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

For a simple tool with one optional parameter and rich annotations, the description is complete. Explains return format, use cases, window choices, data provenance, and caching. No output schema needed due to clarity.

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 the parameter with enum. Description adds default (24h) and behavior guidance (shorter windows show hot right now, longer show steady-state demand). Fully compensates 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 it returns top tools, packs, and call volume over configurable windows. Distinguishable from sibling tools like 'discover_tools' and 'search' by focusing on aggregated trending data from other AI agents.

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?

Lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use case). Explains trade-offs between window lengths. Does not explicitly mention 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 read-only, idempotent, non-destructive. Description adds list of returned fields (title, description, etc.), which is helpful but basic.

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, front-loaded with action and resource. Every word earns its place. No redundant information.

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

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

Given simple tool with 1 parameter, rich annotations, and output schema, description covers purpose, input, and output. Lacks mention of error behavior (e.g., invalid ID), but acceptable for a basic fetch.

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

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

With 0% schema coverage, description must define parameters. It explains 'id' is a 'Listen Notes `id`', adding context beyond schema's type/name. Could be more specific about format, but example in schema helps.

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 verb 'Fetch', resource 'podcast', and identifier 'Listen Notes `id`'. Lists specific fields returned. Distinguishes from sibling tools like 'episode' or 'search'.

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

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

No explicit guidance on when to use vs. alternatives (e.g., when you have an ID vs. searching by name). Misses opportunity to clarify 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 mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral details: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check (live CLOB depth), and response structure. 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 quite long but well-structured: starts with overall purpose, then details each mode, then behavioral nuances. Every sentence adds value, though slightly verbose. It is front-loaded with the core action.

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

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

No output schema exists, so the description must cover return values. It does so explicitly: opportunities array with fields, partition_check object in event mode, fill check behavior. It also references polymarket_fill_risk for custom sizing, providing complete 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?

Schema coverage is 100%, meeting the baseline for 3. However, the description adds significant extra meaning: explains what happens with each parameter (trending_scan for no args, single-event vs cross-event), accepts full URLs, and describes the internal logic (semantic anchor, partition filter). This far exceeds 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes: no-args (trending_scan), event mode, and topic mode, with specific use cases.

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

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

The description provides clear guidance on when to use each parameter (event recommended for specific market, topic for cross-event scanning) and warns against trading when realizable edge is non-positive. It doesn't explicitly contrast with sibling tools like polymarket_edges or polymarket_fill_risk, but the usage is well-defined.

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 safety hints (readOnly, idempotent). The description adds extensive behavioral details: model families, edge calculation, slippage, caching at KV level keyed on all knobs, 1h cache, diagnostics. This goes well beyond annotations and provides deep 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 well-structured, front-loading purpose then detailing model families and knobs. Though long, every sentence adds value. A slightly more concise presentation could improve, but current structure is logical and 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 9 parameters, no output schema, the description comprehensively explains response structure (by_segment, fed_candidates, diagnostics), caching, and model details. It covers everything needed to understand tool behavior and output.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp), default behaviors (slippage_pp 0.3), and special handling for min_partition_leg_kelly. This enhances understanding beyond 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 it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools by specifying its focus on edge detection with multiple model families. The purpose is specific and actionable.

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 good usage context ('what should I bet on today') and explains knobs for filtering. However, it does not explicitly differentiate when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker, which would further 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?

Beyond annotations (readOnlyHint, idempotentHint), the description provides rich behavioral context: response structure (tracked, expired, snapshot_dates), computation of trend and decay, and limits (60-day TTL, daily closes, not intraday). This adds significant value.

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

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

The description is front-loaded with core purpose and is structured logically. It is somewhat verbose but includes necessary details. A bit more conciseness could improve, but it is well-organized.

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

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

Despite no output schema, the description thoroughly explains the response fields and data source, covering tracked, expired, and snapshot_dates with their interpretations and limitations. It is 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%, so baseline is 3. The description mentions days and window with defaults and max, but the schema already provides similar information ('clamp 2-30' vs description 'max 30'). Description adds minimal extra meaning beyond what 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots', and answers specific questions like 'how long has this edge existed and is it shrinking?'. It uses a concrete example to differentiate fresh vs old edges, making the purpose unambiguous.

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

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

The description implies usage context but does not explicitly state when to use this tool over alternatives like polymarket_edges. It describes what it does, but lacks comparative guidance or exclusions.

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 behavior beyond annotations (readOnlyHint, etc.): it explains how it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that partial basket fills lead to unhedged directional positions. 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 front-loaded with the core purpose and uses capitalization for emphasis, but is lengthy. Every sentence is informative; however, it could be slightly more structured with lists or bullet points for readability. Still, no wasted words.

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

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

No output schema exists, but the description fully explains return values for both modes, listing key fields (top_of_book, vwap_fill_price, theoretical_sum, realizable_sum, thin_legs, forced_directional_risk, etc.). It covers all important behavioral aspects and edge cases.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains the difference between single-market and basket modes, how side defaults in basket mode (auto based on partition sum), and how size_usd is interpreted differently for each mode (max spend vs. settlement notional). This adds value beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check' on the Polymarket CLOB order book, distinguishing between single-market and basket modes. It uses specific verbs ('check', 'walks the ladder') and resource ('live CLOB order-book depth'), making it distinct from siblings like polymarket_arbitrage.

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 advises when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the consequences of not using it (theoretical overround not capturable, partial fills converting arb to directional risk), providing clear when-not-to-skip guidance.

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

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

Annotations already declare readOnly and idempotent, and the description adds critical behavioral context: compatibility conditions, skipped leg comparisons, temporal alignment checks, and the fact that matched pairs may be zero. 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 well-structured with clear sections (purpose, modes, response, safety fields) and front-loaded. It is somewhat long but every sentence adds valuable detail. Slightly verbose for an AI agent but acceptable given complexity.

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

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

Despite no output schema, the description thoroughly explains return values (leg-by-leg prices, matched spread, top_spreads_pp) and all safety fields (compatibility_warning, temporal_alignment, skipped counters). For a complex tool with 3 optional parameters, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining how each parameter works (topic auto-fetches, explicit overrides) and provides examples. It goes beyond the schema by clarifying behavior like overriding behavior and topic limitations.

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 computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs (spread, cross-venue) and distinguishes from sibling tools like polymarket_arbitrage by focusing on two venues and safety 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 explicitly defines two modes (topic shortcuts and explicit tickers), warns that most pre-mapped topics return compatibility warnings, and explains safety fields like compatibility_warning and temporal_alignment to guide when the result is meaningful.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds valuable context about scoping and that omitting key lists all keys. 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?

Two sentences tightly packed with essential info: purpose, usage examples, scoping, pairing. No redundancy or filler.

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

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

For a simple one-parameter read tool with no output schema, the description fully covers purpose, usage, scoping, and related tools. No missing 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?

Schema coverage is 100% and schema already describes the parameter's behavior (omit key to list). Description mirrors this, adding no new semantic detail beyond the schema.

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

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

Description clearly states verb ('retrieve' or 'list') and resource ('value previously saved', 'all saved keys'). Explicitly differentiates from sibling tools 'remember' and 'forget' by pairing with them.

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 concrete examples of when to use (target ticker, address, research notes) and notes scoping to identifier. Lacks explicit when-not-to-use, but pairing info guides alternative selection.

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

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

The description discloses the side effect of setting mark_read:true, which flags events as read and affects future calls. This adds transparency beyond annotations, though annotations (readOnlyHint, idempotentHint) contradict this behavior.

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

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

The description is well-structured, starting with the core purpose and then detailing parameters and behavior. Every sentence adds value without redundancy. It is concise yet comprehensive.

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 (source, citation_uri, payload), filtering parameters, the mark_read mechanism, and even provides fallback info (REST endpoint). Given no output schema, it adequately prepares the agent for expected results.

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

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

All five parameters are fully described in the schema (100% coverage). The description adds context by giving examples (e.g., 'sec_8k' for type, ISO timestamps for since) and explaining the effect of mark_read and unread_only, exceeding baseline expectations.

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 pulls fired events from the subscription feed, specifies the return fields, and lists filtering options. It distinguishes from sibling tools by focusing on recent alerts from the feed.

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 context for usage, noting that polls work fine and mentioning an alternative REST endpoint for scripts/dashboards. However, it does not explicitly exclude other tools or provide detailed when-to-use/when-not-to-use 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?

Describes fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic, and parallel call behavior. Adds significant context beyond annotations, which already indicate read-only, idempotent, open-world.

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 paragraph that front-loads purpose with example queries, then efficiently covers functionality, parameters, output, and alternatives. No redundant sentences.

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, it explains return structure and citation URIs. Mentions fallback behavior. Could be slightly more explicit about error handling, but sufficient 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%, but description adds formatting details for 'since' (ISO vs relative with examples), explains 'value' can be ticker or CIK, and clarifies 'type' restriction.

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

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

The description clearly defines the tool as a change feed for a company over a time period, using specific verbs and resource. It distinguishes itself from entity_profile by contrasting use cases.

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

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

Provides explicit guidance on when to use this tool vs. entity_profile. Lacks exclusions for other sibling tools, but the context is clear enough for most scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns a list of similar episodes with specific fields, which is consistent with annotations and provides useful context beyond structured data.

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

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

Two sentences, front-loaded with verb and purpose. Every sentence is informative 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 the output schema exists, the description doesn't need to detail return values. It covers the core functionality, though it could mention limits on the number of recommendations or ordering. Still, it is largely adequate.

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

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

The input schema has one required parameter 'id' (string) with 0% schema description coverage. The description adds that this id is a Listen Notes id, giving semantic meaning to the parameter beyond the raw schema.

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

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

The description clearly states the verb ('Fetch'), the resource ('episode recommendations'), and the input ('given episode by Listen Notes id'). It also specifies what is returned, distinguishing it from sibling tool 'recommendations_for_podcast'.

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?

Usage is implied (when you have an episode id and want similar episodes), but there is no explicit guidance on when not to use this tool or mention of alternatives. No prerequisites or exclusions are stated.

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 convey that the tool is read-only, open, and idempotent, so the description does not need to repeat those. The description adds information about the return format (list of similar podcasts with specific fields), but does not disclose additional behavioral traits such as rate limits or authentication requirements.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and return value. Every word contributes meaning, with no redundancy or unnecessary detail.

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

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

For a simple tool with one parameter, rich annotations, and a likely detailed output schema (implied by the presence of the output schema), the description is sufficiently complete. It covers what the tool does, how to use it, and what it returns.

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 for the parameter 'id', leaving its meaning ambiguous. The description clarifies that 'id' is a 'Listen Notes id', which adds crucial semantics not present in the schema.

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

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

The description uses a specific action verb 'Fetch' and clearly identifies the resource as 'podcast recommendations similar to a given podcast by Listen Notes id'. It also lists the returned fields, distinguishing it from sibling tools like 'recommendations_for_episode' or 'best_podcasts'.

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 the tool: when you need recommendations based on a specific podcast ID. While it does not explicitly mention when not to use or provide alternatives, the context of sibling tool names (e.g., 'recommendations_for_episode') makes the intended use case 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 indicate idempotentHint=true and destructiveHint=false. The description adds scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. No contradictions and adds useful context beyond annotations.

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

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

Description is concise with 4 sentences. Front-loaded with purpose, followed by usage guidance and behavioral details. 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 adequately explains storage, retrieval via recall, and deletion via forget. It covers lifecycle and context (scoped by identifier, persistence). Complete for a simple key-value 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% with both key and value described in the schema. The description does not add further parameter details but is consistent. Baseline score given schema richness.

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 'Save data the agent will need to reuse later' and specifies the resource (key-value pair) and scope (conversation/sessions). It distinguishes from sibling tools 'recall' and 'forget'.

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 advises when to use: 'when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' Also mentions pairing with recall and forget for retrieval and deletion.

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

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

The description goes well beyond the annotations by disclosing cascading internal lookups, graceful degradation of LEI/FIGI enrichment, labeling of identifiers by source, explicit reporting of unresolved identifiers, and that it replaces 2-3 manual lookups. 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 long but intentionally packed with valuable information: multiple user-phrasings, supported types, input formats, output behavior, and fallback semantics. It is front-loaded with purpose and examples, and each sentence earns its place, though it could be slightly trimmed without losing core 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?

Despite lacking an output schema, the description thoroughly covers both supported entity types, what each returns, input acceptance, failure behavior (unresolved field), graceful degradation, and internal cascading. It provides sufficient context for an agent to know when and how to use the tool and what to expect, making it complete for its 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% and the schema already documents the type enum and the accepted input formats (ticker/CIK/name, brand/generic). The description repeats these input forms and adds output-related detail (e.g., returned identifiers, unresolved handling) rather than clarifying parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool resolves a user-spoken name into canonical/official identifiers needed by other tools. It provides specific examples ('ticker', 'CIK', 'LEI', 'RxCUI') and explicitly differentiates from siblings by noting it should be used 'FIRST' when an ID is needed, distinguishing it from tools like entity_profile or search.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to invoke the tool. However, there is no explicit mention of when not to use it or alternative tools for cases where an ID is already known, so it falls short of full exclusionary guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds how it works ('probes each entity with ai_visibility_check') and output format ('ranked list with score, confidence, signal density'). No contradictions.

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

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

Three well-structured sentences. First sentence gives core action and result. Second explains mechanism. Third gives concrete example and output summary. No wasted words, front-loaded with key information.

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

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

Given no output schema, description adequately explains return values (score, confidence, signal density). 4 parameters all covered in schema (100%) and description adds behavioral context. Annotations assure safety. Complete for 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% and description adds value by explaining that 'entities' first entry is treated as subject for narrative. The context parameter is explained as 'disambiguates common names'. This goes beyond the schema's 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?

Description clearly states 'compare AI visibility across multiple entities side-by-side' with specific verb and resource. Distinguishes from sibling tools like ai_visibility_check (single entity) by mentioning multi-entity comparison and ranking. Concrete example 'does Claude know about us as well as our competitors?' reinforces purpose.

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

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

Explicitly states use case: 'competitive AI-marketing audits' and gives a concrete question. Does not explicitly state when not to use, but context and mention of alternatives (pre-existing probes) imply appropriate usage. Clear enough for agent to decide.

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 important behaviors beyond annotations: partial failures degrade gracefully, bundlephobia measurement latency (5-30s first time), and sources_failed listing. Annotations already indicate read-only/idempotent, and the description adds operational details.

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

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

Description is comprehensive yet front-loaded with the core purpose. Some redundancy (e.g., 'fans out' and listing sources) but efficient overall. Could be slightly more concise, but structure is clear.

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

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

Covers all essential aspects: composite nature, sources, return fields summary, partial failure behavior, ecosystem limitation, and version history context. No output schema exists, so description compensates fully.

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

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

Schema has 100% coverage with descriptions. The description adds context: scoped packages accepted, version defaults to latest. While the schema is sufficient, the description reinforces usage, justifying a slight increase above baseline 3.

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

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

The description clearly states the tool's purpose: a composite check combining deps.dev and bundlephobia to evaluate npm packages. It uses specific verbs ('scan', 'fans out', 'returns') and distinguishes itself from sibling tools by focusing on package health checks.

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

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

Explicitly states when to use ('when agent asks is X safe/popular/small') and when not to use ('NPM ecosystem only in v1; other ecosystems use deps.dev:version directly'). Provides clear alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about return fields (title, publisher, audio URL, Listen Notes id) and the tool's role in answering topic/guest queries, going beyond the safety profile. However, it does not mention pagination, rate limits, or other nuanced behaviors, so it is not a perfect 5.

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 three-sentence description is front-loaded with the action and covers purpose, scope, filters, and return values without unnecessary words. It is slightly longer than the minimal version but every sentence contributes 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?

With 8 parameters and an output schema available, the description adequately explains the core search behavior, content types, and key return fields. It omits pagination details and edge cases but is sufficiently complete given the strong annotation coverage and 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?

Schema description coverage is low (38%), and the description lists filter categories (type, language, genre_ids, episode length, date sorting) but does not detail individual parameters like offset or the exact semantics of len_min/len_max. It provides some compensation for the schema's sparse parameter descriptions but not enough to fully bridge the gap.

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 the Listen Notes podcast index across podcasts, episodes, curated lists, and people, with specific filters and returns record fields. This distinguishes it from more targeted sibling tools like 'podcast' and 'episode'.

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

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

The description implies use cases (finding content by topic, guest, or show name) but does not explicitly state when to prefer this tool over alternatives or provide exclusions. No alternative tools are mentioned, leaving usage guidance to inference.

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 reveals behavioral details beyond annotations: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K character cap with truncation flagging, and returns character offsets for verification. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent with this behavior.

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

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

The description is concise but contains all necessary information. The first sentence immediately states the core purpose. However, the final sentence about embeddings and cap could be integrated more naturally, and the description is slightly longer than minimal.

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 three parameters, no output schema, and moderate complexity (embedding, chunking, cap), the description provides complete context: return type (passages with offsets), technical details (BGE, windows, cap), and integration guidance (pairing with ask_pipeworx_grounded).

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 text, query, and limit. The description adds examples for the query parameter and explains the purpose of the text parameter ('pass the text you already pulled'), which adds meaning beyond the schema alone.

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 performs semantic search inside a fetched record, using a natural-language query, and returns passages with offsets. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded and explicitly says 'use when the record is too big to cram into the prompt.'

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

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

The description provides explicit guidance on when to use this tool (when records are too large for the prompt) and what not to use it for (not a general search tool). It also mentions pairing with ask_pipeworx_grounded, giving alternative workflow 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?

Adds behavioral context beyond annotations: returns new subscription id, requires OAuth, type-specific params, delivery channels with constraints (SMS cap, webhook signing, auto-disable after 10 failures). 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?

Front-loaded with core purpose, then structured into types and delivery channels. A bit lengthy due to examples, but all information is relevant. Could be slightly more concise, but clarity prioritizes completeness.

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 covers return value (subscription id), all parameters, prerequisites, and edge cases (webhook secret one-time return, SMS verification, auto-disable). Completely addresses what an agent needs to know to invoke the tool correctly.

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

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

Schema coverage is 100%, but description enriches each parameter with concrete examples and constraints (e.g., type enum, params structure for each type, delivery details including phone verification and webhook signing). Adds significant value beyond schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream. It mentions specific subscription types and delivery channels, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly states when to use (for proactive monitoring), prerequisites (Pipeworx OAuth account), and limitations (anonymous/BYO cannot persist). Provides examples for each type and delivery channel, and implies alternatives such as list_subscriptions and recent_alerts.

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, which ensure safety. The description adds meaningful behavioral context: it returns category-bucketed examples with tool+argument shapes, and it's the onboarding entry point. This complements the annotations without contradiction.

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

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

The description is a single paragraph that front-loads the core purpose and usage. It is information-dense but remains readable. Minor improvement could be breaking into bullet lists, but overall it wastes no sentences.

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 (one optional param, no output schema), the description fully explains what it returns (category-bucketed examples, exact tool+argument shapes), when to use it (onboarding), and parameter behavior. No gaps remain.

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

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

Schema coverage is 100% with a single optional topic parameter. The description adds value by explaining that omitting it gives a full cross-category spread and lists example topic values (finance, pharma, etc.), which is beyond what the schema description 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 that the tool is the onboarding entry point that returns category-bucketed example questions and how to ask them. It uses specific verbs ('returns', 'call') and distinguishes from sibling tools by focusing on getting started and learning the agent's capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear when-to-use guidance and implicitly directs away from other tools until the user is oriented.

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 ownership enforcement and deactivation behavior beyond annotations (which indicate non-destructive). Aligns 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?

Two concise sentences, front-loaded with action and id, then constraint. 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, ownership, and side effect. Lacks explicit return value, but acceptable given simplicity and 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?

Only one parameter 'id' with schema coverage 100%. Description adds no extra meaning beyond schema, so baseline 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 states specific verb 'cancel' and resource 'subscription by id'. Clearly distinguishes from sibling 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement and that the row is deactivated (not deleted). Implies when to use, but lacks explicit when-not or alternatives.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent) by explaining the two routing pipelines, the verdict enum, the distinction between 'could_not_verify' and 'unsupported', the error structure, and the use of verbatim evidence with citations. 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?

Though longer than typical descriptions, every sentence is packed with essential information: trigger phrases, routing logic, return values, error semantics, and performance benefits. The structure is logical and front-loaded with user-facing phrasings, making it 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?

Given the tool's complexity (two pipelines, multiple verdict types, error handling) and lack of output schema, the description is remarkably complete. It explains return values, error cases, routing decisions, and even the advantage over sequential calls, covering all necessary context for an agent to invoke it correctly.

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

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

Schema coverage is 100% with both parameters described, but the description adds valuable nuance beyond the schema for tolerance_pct—explaining it overrides claim wording, suggesting values for hallucination detection, and noting the default cap of 5. This enhances the parameter meaning beyond mere type/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 identifies the tool as natural-language claim verification against authoritative sources, using specific verbs like 'fact check' and 'verify the claim that...'. It distinguishes itself from sibling tools by focusing on factual claims and explicitly mentioning two pipelines (SEC EDGAR for financial claims, grounded pipeline for others).

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 whenever the agent needs to check whether something a user said is factually correct', providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools, though the mention of replacing 4-6 sequential calls implies a shortcut.

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