Podcastindex

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds value by specifying default model, optional Anthropic key dependency, cost implications (BYO key, direct payment), and return format (per-model data + combined view). This goes beyond 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 three sentences: first sentence defines core functionality, second details models and return, third lists use cases. No redundant or unnecessary information. Efficient and well-structured.

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

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

Despite lacking an output schema, the description explains return format (per-model fields and combined view). It covers default behavior and optional configurations. Could mention that scores are 0-100 (already stated) or any limitations, but overall sufficient for a read-only probe 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 provides descriptions for all 4 parameters (100% coverage). The description enriches these with examples ('Pipeworx', 'OpenInvoice'), clarifies conditional use of _apiKey, and explains that context helps disambiguate. 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 the tool probes LLMs for entity visibility and scores 0-100 per model. It specifies the verb ('Probe') and resource ('LLMs for visibility'). However, it does not explicitly differentiate from sibling tool 'scan_competitor_ai_presence', which may perform a similar function, so purpose is clear but lacks sibling distinction.

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 contexts like AI-marketing audits and pre-launch brand checks, but does not provide explicit when-to-use versus when-not-to-use guidelines or mention alternative tools (e.g., scan_competitor_ai_presence). Usage is implied but not fully specified.

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 non-destructive. The description adds value by detailing the routing mechanism (4,552 tools), citation URIs, and performance characteristics ('one fast call, works on every tier'). It could mention any limitations on subjective questions, but that's minor.

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 most important instruction ('PREFER OVER WEB SEARCH'), then explaining functionality, usage guidelines, examples, and alternatives. Every sentence serves a purpose, and the length is justified by the detail needed.

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 lack of an output schema, the description fully explains what the tool returns (structured answer with citations) and how it works. It covers when to use, when not to, and provides diverse examples. No gaps remain given the tool's complexity.

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

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

Schema coverage is 100%, with detailed descriptions of the question parameter and aliases. The description provides examples but does not add significant meaning beyond the schema. Given high coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to a large set of verified sources and returns structured answers with citations. It uses specific verbs ('routes', 'fills arguments', 'returns') and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly tells when to prefer this tool over web search, when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions), and provides numerous examples of appropriate queries.

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 significant context beyond annotations: it reveals the refusal mechanism with specific reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), return structure (answer, evidence, confidence, source, fetched_at), and the extra LLM call cost. Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false; description does not contradict and enriches understanding.

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 relatively concise for the amount of information it conveys. It is front-loaded with the core purpose, followed by usage guidance and behavioral details. However, it could be slightly trimmed without losing value, such as listing all refusal reasons in a more compact format.

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 (high-stakes, refusal modes, cost trade-off) and the absence of an output schema, the description is remarkably complete. It explains the return value structure, all possible refusal reasons, and the cost implication. There are no apparent gaps for an agent to understand how to use this tool effectively.

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 parameters already described well (including aliases). The description adds that the question is in 'natural language' and mentions aliases, but this is minimal added meaning. Baseline 3 is appropriate since schema does the heavy lifting.

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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains it routes queries through 4,552 tools, fetches data, and extracts answers only from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing groundedness and refusal behavior.

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 using this tool for high-stakes reads where answers will be quoted or acted on, and recommends preferring 'ask_pipeworx' for casual lookups due to the extra LLM call cost. This provides clear when-to-use and when-not-to-use guidance, referencing the sibling tool.

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, destructiveHint. The description adds extensive behavioral context: resolver contract with match confidence, parent event extraction, news fallback, safety short-circuits for low-confidence and closed markets, wide-spread handling, and cancellation rule risk. This goes far beyond what annotations provide.

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

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

The description is very long and dense, but it is structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). It front-loads the core purpose. However, it could be more concise given the length; some users may find it overwhelming.

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 3 parameters, no output schema, and complex behavior, the description is remarkably complete. It covers inputs, internal resolution process, response structure for market, analysis, evidence, parent events, news fields, safety mechanisms, and resolution rules. All relevant aspects are addressed.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds further meaning: examples of market_input, explanation of depth levels (quick vs thorough), and include_raw behavior (summary vs full payloads). This enhances understanding 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 the tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from sibling tools by being the only one focused on Polymarket bet research.

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 usage examples are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly mention when not to use, but the purpose is clear enough to avoid misuse.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses key behaviors: correct handling of off-calendar fiscal years, results sorted by primary metric, and return of paired data with citation URIs. It also quantifies efficiency gain (replaces 8–15 sequential lookups). 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 efficiently structured with front-loaded examples, then behavioral details, then per-type specifics. It is comprehensive yet not overly verbose, but could be slightly tighter with removal of redundant phrases.

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 two parameters with full schema coverage, clear annotations, and no output schema, the description provides sufficient context: it explains what data is retrieved per type, how results are sorted, and that citations are included. No further information is needed for correct tool invocation.

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

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

Schema coverage is 100%, and the description adds significant value by detailing what each type retrieves (e.g., for company: 'LATEST 10-K revenue + net income + cash + long-term debt'; for drug: 'FAERS adverse-event counts, FDA approval counts, active trial counts'). Examples like 'AAPL', 'MSFT' and 'ozempic', 'mounjaro' clarify expected values.

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 performing side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It provides specific example queries ('compare X and Y', 'rank these companies') and distinguishes itself from sequential 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 recommends preferring this tool over sequential single-pack lookups for comparisons and provides example use cases. However, it does not explicitly state when not to use it (e.g., for single entity lookups), though the context makes that 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behaviors: parallel decomposition to 4,552 tools, output format (evidence+confidence+source+citation+gaps[]), expected time (15-60s), and limitation (empty gaps for news topics). 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?

Description is dense but every sentence serves a purpose: caveats, usage, behavior, alternatives, and expected output. Front-loaded with important account/alternative info. Slightly long but efficient for the complexity.

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

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

Covers all key aspects: prerequisites (account), inputs (question+depth), alternatives, process (parallel decomposition), output format (findings packet with gaps), limitations (news), and timing. No output schema, but description adequately explains return structure.

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

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

Schema coverage is 100% (both parameters documented). Description adds meaning: for 'depth', explains number of facets per option and payment requirement; for 'question', clarifies that broad/multi-part is fine. This goes 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 performs 'grounded multi-source research across Pipeworx's 1160 structured data sources in one call', distinguishing it from siblings like ask_pipeworx (single lookup) and providing specific use cases. The verb 'research' and resource 'structured data sources' make the purpose specific.

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 this tool (broad/multi-part questions over structured data) and when not (breaking news, single lookup), with direct alternatives (ask_pipeworx). Also mentions account requirement and that 'thorough' needs paid plan.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable specifics: returns top-N relevant tools with full schemas and curated examples, and that results are ready to call directly. No contradictory information.

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

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

Two paragraphs, no superfluous sentences. First sentence captures purpose, subsequent sentences add usage guidance, return format, and a key instruction. 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?

No output schema exists, so the description bears full burden. It adequately explains what the tool returns (top-N tools with names, descriptions, full schemas with examples) and that results are immediately callable. The instruction to call first provides operational 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%, so baseline is 3. The description adds meaning by explaining that 'query' is a natural language description and listing aliases (q, task, search, description). It also provides two concrete examples in the schema that illustrate usage.

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: finding tools by describing data or task. It specifies the return (top-N tools with full schemas) and distinguishes from siblings by positioning itself as the first call to discover 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. Also lists many domains where it applies, giving clear context for when to use.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds valuable behavioral details: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), discloses that patents part soft-fails after May 2025, and explains required input format (ticker or CIK vs names). 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 relatively long but front-loaded with examples and then details about return fields and sources. Every sentence serves a purpose, though minor redundancy could be trimmed. Appropriate for the tool's complexity.

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

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

Given no output schema, the description thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers the tool's scope and limitations (patents sunset, name unsupported), making it complete for agent interpretation.

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 the schema already documents parameters adequately. The description adds minor clarification: for 'value', it emphasizes names not supported and suggests using resolve_entity. For 'type', it merely restates the enum. This adds marginal 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 the tool provides a full cross-source profile of a US public company in one parallel call, with explicit example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from siblings by recommending preference over chaining single-pack lookups for holistic views.

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 when to use (user asks for holistic view) and when not (if only have a name, use resolve_entity first). It also guides against alternatives, stating 'ALWAYS PREFER' over chaining individual lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent. The description adds value by listing the returned fields (title, description, publish date, duration, audio URL, episode/season numbers) and providing a concrete example. No additional behavioral details (e.g., rate limits) are needed given the annotations cover safety.

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

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

The description is extremely concise: two sentences and an example. Every sentence serves a purpose (purpose, output, usage example). No fluff or redundancy.

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

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

Given the tool's simplicity (no output schema, no nested objects), the description is complete. It covers what the tool does, what it returns, and how to call it. The example fills any remaining gaps about parameter formatting. No additional context is 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?

Schema coverage is 100% with all three parameters described. The description adds an example using feed_id and max, which reinforces usage but does not add new semantic meaning beyond what the schema provides. A score of 3 is appropriate as the description does not significantly extend parameter understanding.

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: 'List recent episodes for a podcast by its Podcast Index feed ID.' It specifies the resource (episodes), action (list), and required identifier (feed ID). The example further clarifies usage, and the tool is clearly distinct from siblings like search_podcasts or get_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?

The description implies when to use the tool (when you have a feed ID and want episodes) but does not explicitly state when not to use it or name alternatives. The example hints at the flow from search_podcasts, but direct guidance is missing. Nonetheless, the context is clear for an AI agent.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about clearing sensitive data, aligning with and enhancing 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?

Three sentences, front-loaded with action, followed by usage guidance and sibling pairing. No wasted words.

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

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

For a simple one-parameter tool with comprehensive annotations, the description covers purpose, usage, and siblings. It does not explain return values (no output schema) or error handling, but these are optional given the tool's simplicity.

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

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

Schema coverage is 100%, and the description does not add additional meaning beyond the schema's description of the 'key' parameter. 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 action (delete) and the resource (memory by key). It distinguishes itself from sibling tools 'remember' and 'recall' by pairing with them, making its 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?

Explicitly provides when-to-use scenarios: stale context, task completion, clearing sensitive data. However, it does not include explicit negative guidance (e.g., when not to use) nor alternatives beyond mentioning siblings.

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 valuable context beyond annotations: fetches page, extracts title/description/key links, outputs standard markdown format. Annotations indicate readOnly, openWorld, idempotent, non-destructive, which description supports 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?

Three sentences: purpose+mechanism, output format, use cases. No redundant 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?

No output schema, but description explicitly states output is a single text blob ready to drop at site-root/llms.txt. Fully explains return value for agent to understand usage.

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

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

Schema coverage is 100% (baseline 3). Description reinforces parameter meaning by stating 'Fetches the page' for url and mentions max_links default and max values. Adds 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?

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying verb, resource, and outcome. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on creating the file itself.

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: indexing a client's site, drafting for own project, auditing competitor. Provides clear context but lacks explicit 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?

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds context on the specific metadata fields returned (title, author, etc.), which is valuable beyond the annotations.

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

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

Two sentences plus an example. Every word serves a purpose. The description is front-loaded with the verb and resource.

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

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

For a simple read-only tool with two parameters and no output schema, the description fully covers purpose, parameters, and return content. No gaps given the 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%. The description adds value by explaining the purpose of feed_id and providing a concrete example. It also notes _apiKey is optional for higher limits.

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 'Get', resource 'full metadata for a single podcast', and identifier 'by its Podcast Index feed ID'. It distinguishes from siblings like search_podcasts and 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 specifies when to use (to get a single podcast by feed ID) and provides an example. It does not explicitly exclude alternatives, but context from sibling names implies the use case.

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, non-destructive. Description adds return field details but no extra behavioral traits beyond what annotations convey. Adequate but minimal added 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?

Two sentences, front-loaded with purpose, efficient and without waste.

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 list tool: specifies return fields, usage context, and no output schema needed. No missing critical information.

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

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

Schema covers 100% of parameter documentation including description for 'include_inactive'. Description adds no additional parameter meaning. Baseline 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 lists active subscriptions, specifies returned fields (id, type, etc.), and distinguishes from sibling subscribe/unsubscribe 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?

Explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context relative to siblings.

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

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

The description goes beyond the annotations by disclosing rate limits ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the fact that the team reads digests daily. This adds valuable behavioral context that annotations alone do not provide.

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

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

The description is concise (3 sentences) and front-loaded: the first sentence states the purpose, the second covers usage scenarios, and the third adds behavioral notes. Every sentence adds value with no redundancy.

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

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

Given the tool has 3 parameters (one with enum, one nested object) and no output schema, the description adequately covers when to use, how to use, constraints (rate limit, quota-free), and what to specify (type, message, optional context). Nothing essential is missing.

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?

Although the schema covers all parameters (100% coverage), the description adds meaningful context: it explains the enum options for 'type', reiterates that 'context' is optional, and provides formatting guidelines for 'message' (be specific, 1-2 sentences, 2000 chars max). This enhances understanding 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 is for sending feedback about bugs, missing features, data gaps, or praise. It uses specific verbs ('Tell the Pipeworx team something is broken, missing, or needs to exist') and distinguishes itself from sibling tools by being a feedback channel rather than a data retrieval tool.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and provides guidance on what not to do ('don't paste the end-user's prompt'). It does not explicitly mention alternatives, but the sibling tools are all different in nature, so the usage context is clear.

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

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

Adds behavioral context beyond annotations: data source (CF analytics-engine), no PII, caching (5min-1h). Complements readOnlyHint and idempotentHint.

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?

Informative paragraph with bullet-like points. Slightly wordy but front-loaded with purpose. Efficient for the content.

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

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

Comprehensive for a simple one-parameter tool with rich annotations. Covers data source, privacy, caching, and use cases. 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?

Schema has 100% coverage with enum and description. Description adds semantics: shorter windows surface hot right now, longer show steady-state demand. Adds 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?

Clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and specific resources differentiate it from siblings like 'trending'.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment). Also explains window trade-offs. Missing explicit exclusions or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: monotonicity checks, partition-sum computations, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slug threshold), and fill check (theoretical vs realizable edge). 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 well-structured with clear sections and front-loaded summary. However, it is quite verbose with technical details (e.g., Jaccard threshold, placeholder fraction) that are not essential for basic tool selection. Could be slightly more concise while remaining informative.

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 explains the response format (opportunities array, partition_check object) and the fill check mechanism. It does not mention error cases or behavior when no opportunities are found. Given the complexity, it covers most but not all contextual needs.

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

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

Schema coverage is 100% with basic descriptions, but the tool description adds significant value: explains the difference between event and topic modes, provides example slugs, clarifies that full URLs are accepted, and details what each mode does. This surpasses 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and mentions related tools like polymarket_fill_risk, providing strong differentiation from siblings.

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

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

Explicitly describes when to use each parameter: no args for trending scan, event for a specific market, topic for cross-event scanning. Recommends event for specific markets and explains benefits of topic mode. Also references polymarket_fill_risk for custom sizing, guiding appropriate tool selection.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: caching (1h at KV level), model details (FRED log-returns, GDELT, partition_overround with per-sport α), and diagnostics for empty segments. 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 well-structured with segment headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and bullet-point details. It front-loads the core purpose. While verbose, every sentence adds value given the tool's complexity. Could be slightly more concise, but appropriate for the subject matter.

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

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

The tool has 9 parameters, no output schema, and no nested objects. The description explains the response structure (by_segment, fed_candidates, _diagnostics) and what each opportunity contains (edge_pp_net, kelly_fraction, liquidity, etc.). It also addresses why segments might be empty via diagnostics. This is fully complete for an exploratory tool without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. However, the description goes beyond schema definitions by explaining each parameter's purpose and usage context (e.g., min_kelly 'Skips opportunities that are too small to bet sensibly', max_spread_pp 'Tradeable-edge filter', slippage_pp with Polymarket fee context). This adds significant semantic value.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb ('Scan'), resource ('top Polymarket markets'), and the unique value proposition ('disagree with market price'). This distinguishes it from siblings like polymarket_arbitrage and polymarket_kalshi_spread.

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 frames the tool as 'Built for what should I bet on today' and notes it avoids paging hundreds of markets. It provides guidance on knobs like min_liquidity, max_spread_pp, and slippage adjustment. While it doesn't explicitly state when not to use, the context is clear enough for an 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?

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it reads from snapshots, returns time-series data with trend and decay calculations, identifies expired opportunities, and explains snapshot date gaps. 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 detailed but efficiently packed with essential information. It front-loads the purpose and provides structured output details. Slightly longer than minimal but each 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?

Despite lacking an output schema, the description thoroughly explains the return fields (tracked, expired, snapshot_dates) and their meanings. It covers edge cases (gaps, limitations) and provides sufficient context for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds default values and context (lookback, window family) but does not significantly extend 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 the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a precise verb-resource combination and distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical persistence rather than current 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 provides strong guidance on when to use the tool, contrasting fresh vs. old edges. It explains the output structure and mentions limitations (60-day TTL, snapshot gaps). However, it does not explicitly state alternatives or when not to use it.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds detailed behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), describes basket mode returns including thin_legs and forced_directional_risk. 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 relatively long but well-structured with sections for single-market and basket modes. It uses bold for emphasis and lists return fields. Every sentence provides value, though slightly verbose for a concise definition.

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 (two modes, numerous return fields, no output schema), the description is comprehensive. It covers both modes, return values, usage guidance, and risk warnings, fully compensating for the lack of 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 100%, but the description adds significant meaning beyond the schema: explains side defaults (auto for basket), size_usd interpretation for buys vs sells and basket settlement notional, and clarifies that 'market' and 'event' are mutually exclusive.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and specifies two modes (single-market and basket). It distinguishes from siblings by explicitly saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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 the tool (before arbitrage or edge trades above $500) and warns about pitfalls like theoretical overround being uncapturable on thin books and partial basket fills creating unhedged positions.

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 (readOnly, idempotent, non-destructive), description explains compatibility_warning conditions, temporal alignment, and skipped cross-type/subtype counters, providing deep behavioral context for interpretation.

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

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

Well-structured with front-loaded purpose and clear sections, but the detailed explanation of safety fields makes it slightly verbose. Still, 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?

Despite no output schema, description thoroughly explains response fields (legs, top_spreads_pp, compatibility_warning, temporal_alignment, counters) and edge cases. Covers all necessary context for a 3-param optional 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 covers all 3 parameters with descriptions. Description adds semantics by explaining the two modes and how each parameter overrides the other, making usage clear. No additional parameter info needed.

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 defines the tool as a cross-venue spread between Kalshi and Polymarket for the same question, with two modes and response details. It differentiates from siblings like polymarket_arbitrage by focusing on inter-venue comparison.

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 describes two usage modes (topic shortcuts vs explicit tickers) and warns that most shortcut topics yield compatibility warnings, advising against assuming tradeability. Could be improved by directly contrasting with sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by explaining the scope (anonymous IP, BYO key hash, or account ID) and the ability to list all keys, which is not covered 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 three sentences, front-loaded with the core function, then usage examples, then scope and pairing. 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 single-parameter tool with read-only semantics, the description covers the two modes (with/without key), scoping, and relationship to siblings. No gaps given the 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% with a description for the key parameter. The tool description clarifies that omitting the key lists all saved keys, adding meaning beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys. It distinguishes from siblings 'remember' and 'forget' by referencing them specifically.

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 use cases (e.g., retrieving user's target ticker) and states when to omit the key. It also mentions pairing with 'remember' and 'forget', giving 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?

The description discloses that mark_read:true flags events as read and affects subsequent calls, but this contradicts the readOnlyHint=true annotation which implies no state mutation. This is a serious inconsistency.

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

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

The description is concise and front-loaded with the main purpose. Every sentence adds value without redundancy, and the 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?

The description covers the return format, filtering, mark_read behavior, and alternative access. It is fairly complete for a read tool, though the annotation contradiction dampens trust in behavioral completeness.

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

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

While the input schema already describes all parameters (100% coverage), the description adds meaningful context such as an example type ('sec_8k'), the effect of mark_read, and output fields. This goes beyond the schema's minimal 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 pulls fired events from a subscription feed, specifying the resource and action. It distinguishes itself from siblings by mentioning the alternative REST endpoint, 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 provides clear context on when to use the tool (pulling recent alerts) and mentions an alternative for scripts/dashboards. It lacks explicit exclusionary guidance but is sufficient for typical usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds significant context: fans out to multiple sources, explains fallback logic, mentions rate limits for GNews, and notes USPTO sunset. 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 front-loaded with user queries and well-organized, but slightly verbose with multiple details. Each sentence serves a purpose, but could be streamlined without losing value.

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

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

Given the tool's complexity (multiple sources, fallbacks, window parameter), the description is comprehensive. It covers return structure (changes[], total_changes, citation URIs) and edge cases, making it self-contained despite 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?

Schema coverage is 100%; description explains the `since` parameter format (ISO date or relative shorthand like '7d'), suggests '30d' for monitoring, and clarifies `value` accepts ticker or CIK. Adds meaningful guidance 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 explicitly states the tool provides a change feed for a company, with example queries like "What's new with X". It distinguishes from sibling entity_profile by stating when to use the alternative.

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 vs entity_profile, explains fallback behavior between GDELT and GNews, and notes the USPTO soft-fail. It also suggests typical `since` values like '30d'.

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 write, idempotent, non-destructive. Description adds meaningful context: key-value scoping, persistence differences between authenticated and anonymous sessions (24h), which goes beyond annotations.

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

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

Four sentences, front-loaded with purpose. Every sentence adds value: purpose, usage trigger, storage details, pairings. 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 simplicity (2 params, no output schema, no nested objects), the description completely covers what an agent needs to know to use the tool effectively. Slight deduction for not mentioning return value, but not critical for a write operation.

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

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

Schema coverage is 100% with clear descriptions for both key and value. The description provides naming examples (e.g., 'subject_property') but adds little beyond what the schema already conveys. 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 explicitly states the tool saves data for reuse, with verb 'save' and resource 'data'. It distinguishes from sibling tools recall and forget by mentioning them as partners.

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

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

The description clearly advises using this tool when discovering something worth carrying forward, and mentions pairing with recall/forget. It lacks explicit 'when not to use' but provides strong contextual 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, openWorld, idempotent, non-destructive. The description adds important behavioral context: each call cascades through multiple endpoints (replacing 2-3 manual lookups), and it specifies the exact return fields per type (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug). 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?

Description is a single paragraph that starts with illustrative examples and then provides details on supported types and outputs. While efficient, it could be more structured (e.g., bullet points) for even quicker scanning. Every sentence adds value, and it is appropriately sized for the complexity.

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

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

Given two entity types with distinct output structures, no output schema, and 100% input schema coverage, the description covers what each type returns including citation URIs. It explains the multi-endpoint cascade. Minor gap: no explicit list of possible return fields beyond the examples, but sufficient for a lookup tool.

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

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

Schema covers both parameters with 100% description. The description enriches by providing concrete examples for each type (e.g., 'AAPL', '0000320193' for company value; 'ozempic', 'metformin' for drug value) and clarifying the enum values for 'type'. This adds meaning beyond the bare 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?

Description opens with concrete user queries (e.g., 'What's the ticker for…') and clearly states the tool resolves names to canonical identifiers. It distinguishes itself from siblings by noting that other tools require these IDs as input. The verb 'resolve' plus specific resource types ('company', 'drug') make 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also details supported entity types and their outputs. However, it does not explicitly state when not to use this tool or list alternative tools, missing a slight edge in completeness.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds behavioral context by explaining it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. No negative behaviors like rate limits are mentioned, but it's sufficient given the safety profile.

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

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

The description is concise with 3-4 sentences, starting with the core purpose. Every sentence adds value: the process, example use case, and output format. 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 no output schema and moderate complexity (4 params, composite tool calling another tool), the description covers the essential aspects: internal call to ai_visibility_check, output structure, and use case. It could mention performance implications or limits on entity count, but overall complete for typical usage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional parameter-level meaning beyond the schema; it only reiterates the entities parameter's role as subject and competitors. No new parameter details are provided.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces which entity is most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check and compare_entities by being specifically for competitive AI-marketing audits.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' and an example question. It implicitly suggests using ai_visibility_check for single entities, but does not explicitly state when not to use this tool or list alternatives beyond the sibling 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 indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: external service calls, potential 5-30s delay on bundlephobia first measurement, partial failures handled gracefully with 'sources_failed' field, and that other parts still return even if one source times out.

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 detailed and informative, front-loading the core purpose. Every sentence adds value, though slightly verbose. Could be trimmed slightly but remains clear and 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?

Given complexity (multiple external sources, no output schema), description thoroughly explains return format (summary block, advisories, links, versions) and handles edge cases like partial failures and first-measurement delay. 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 descriptions already, but description adds: scoped packages accepted (e.g., @types/node) and default to latest version when omitted. This enriches parameter understanding 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?

Description clearly states the tool performs a composite safety/popularity/size check for npm packages, using specific verbs and resources (fans out across deps.dev and bundlephobia). It distinguishes from siblings by being uniquely focused on npm package evaluation.

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

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

Explicitly tells when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost'. Also specifies NPM only in v1 and directs users to other ecosystem tools for PyPI/Maven/Cargo/Go, providing clear exclusions and 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 indicate read-only, idempotent, non-destructive. Description adds that it searches an open database and returns specific fields, providing useful behavioral context beyond annotations.

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

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

Very concise: three sentences plus an example. Every sentence is informative, 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?

Description fully covers the tool's purpose and return values. No output schema needed as description lists return fields. Schema covers parameters completely.

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 parameters described. Description includes an example demonstrating parameter usage, adding practical meaning beyond schema.

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

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

Description clearly states it searches podcasts by name or keyword, returns specific fields like title, author, etc. It is distinct from siblings like 'episodes' or 'get_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?

Provides an example showing typical usage, but does not explicitly state when not to use or mention alternatives. However, context signals are clear and the example guides usage.

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

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

Beyond annotations (readOnly, idempotent), the description reveals embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K, with truncation flag), and return details (offsets, similarity scores). 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, front-loaded with main action, then detailed behavior and usage. No fluff; every sentence contributes necessary 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?

Despite lacking an output schema, the description sufficiently explains return format (passages with offsets and scores). Covers complexity (large texts, embedding model, truncation) and integration with sibling tools. Complete for its purpose.

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

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

With 100% schema coverage, the description adds value by providing examples for query (e.g., 'supply-chain risk'), explaining limit defaults and range, and noting text max size. Enriches understanding 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 uses a specific verb ('search INSIDE') and resource ('fetched record'), and distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded. Clear examples (SEC 10-K, article) solidify the 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 when to use: when the record is too large for the prompt. Also gives an alternative (ask_pipeworx_grounded) and explains the workflow pairing. No ambiguity.

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 context beyond annotations: describes subscription creation behavior, returns id, requires OAuth, and details delivery channels with constraints (sms 10/day cap). No contradiction with annotations (idempotentHint=true but creation is typically not idempotent; description doesn't address idempotency, but no contradiction).

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

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

Description is detailed but well-structured: starts with purpose and return value, then prerequisites, then types, then delivery options. Could be slightly more concise, but 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?

Thoroughly covers subscription creation with all key aspects: type enumeration, parameter requirements, delivery channels with constraints, and return value. No output schema, but the description adequately explains the response.

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%. Description adds value by explaining type-specific filter parameters with examples (e.g., sec_8k requires ticker + optional items, clinical_trial requires sponsor or condition) and clarifies delivery constraints (email, sms verification, webhook signing).

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+resource: 'Create a proactive monitoring subscription to a live-data event stream' and identifies return value 'Returns the new subscription id'. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (Pipeworx OAuth account, not anonymous/BYO) and lists supported types with examples. Does not explicitly state when not to use or compare to siblings, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detail on return structure (category-bucketed examples with tool+argument shape) and effect of topic parameter.

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?

While not overly long, the description is front-loaded with key purpose. Each sentence adds value, but 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?

For a non-complex tool with one optional parameter and no output schema, the description adequately explains what is returned (category-bucketed example questions with tool+argument shape) and when to use it.

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

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

Schema coverage is 100% with parameter description. Description adds context by listing example topic values and stating omission gives cross-category spread.

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 is the onboarding entry point, returns category-bucketed example questions with exact tool calls, and distinguishes itself from siblings like ask_pipeworx, discover_tools, etc.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', and describes when to use topic parameter.

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 destructiveness. The description adds value by specifying the returned fields (title, author, categories, artwork, trend score) and an example, but does not discuss ordering or caching behavior. 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 plus an example, all front-loaded with the main purpose. No wasted words; efficient and easy to parse.

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

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

For a read-only tool with 4 parameters (all optional) and no output schema, the description covers the purpose, return fields, and an example. It is missing explanation of the `_apiKey` parameter and any pagination details, but overall 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 coverage is 100%, so baseline is 3. The description adds an example and mentions filters, but does not explain the `_apiKey` parameter, which is described only in the schema. This omission slightly reduces value added.

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 'Get' and the resource 'trending podcasts' with context 'across the open podcast database, ranked by recent activity'. It distinguishes itself from sibling tools like 'episodes' or 'search_podcasts' by focusing on trending content.

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 ('Optionally filter by language or category') and provides an example, giving clear context. However, it does not explicitly state when to use this tool vs alternatives like 'search_podcasts' or 'episodes'.

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 context beyond annotations: ownership enforcement, deactivation vs deletion, and historical data retention via recent_alerts. Annotations already indicate idempotent and non-destructive, which is consistent with the description.

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 covering action, constraint, and behavioral outcome. No unnecessary words.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description fully covers purpose, constraints, and side effects. Mentions integration with 'recent_alerts' for continuity.

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

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

Schema covers 100% of parameter description. The description adds context that the id must belong to the user due to ownership enforcement, going beyond the schema's uuid identification.

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 action: 'Cancel a subscription by id'. Differentiates from siblings like 'subscribe' and 'list_subscriptions' by explicitly stating the cancellation action and ownership constraint.

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?

States ownership enforcement ('only cancel your own subscriptions') and behavior ('deactivated, not deleted, history preserved'). Implicitly guides when to use (own subscriptions) but does not explicitly mention alternatives for full 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?

Annotations already declare safety (readOnly, idempotent, not destructive). Description adds return format (verdict types, structured form, citation, delta) and efficiency (replaces multiple calls). 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?

Description is dense but well-structured: opens with query patterns, states usage, clarifies scope, lists return values, and notes efficiency. Could trim a few words but each 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?

Tool is complex (NL parsing, entity resolution, data lookup), yet description covers input, output, scope limitations, and behavioral advantages. No output schema but return format is clearly enumerated, making it complete for selection and invocation.

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

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

Only one parameter 'claim' with 100% schema coverage. Description adds concrete examples ('Apple's FY2024 revenue was $400 billion') that exceed schema description, providing useful context for agents.

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

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

Description clearly states it is for natural-language claim verification, specifically company-financial claims for US public companies. It provides example queries and verb phrases (e.g., 'fact check', 'verify the claim that…'). No sibling tool overlaps, so distinctly establishes 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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides typical query patterns. Implicitly limits to financial claims but lacks explicit when-not-to-use or alternatives.

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