Healthdata

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

The description adds significant behavioral context beyond annotations: it explains the scoring mechanism (0-100), default model, and the need for an API key for Anthropic. It also details the return structure (scores, confidence, signals, raw_response, combined view). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose and then adds necessary details. Every sentence contributes meaningfully, and there is no redundancy or fluff.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is fully informative. It explains what the tool does, how to configure it, and what to expect in the response. The lack of an output schema is compensated by mentioning the return fields.

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

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

The schema already provides 100% description coverage for all 4 parameters. The description adds value by clarifying defaults (Workers AI), the purpose of the API key (BYO), and the context parameter for disambiguation. It does not repeat schema but provides helpful usage tips.

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: probing LLMs for knowledge about an entity and scoring visibility. It specifies the verb 'probe' and resource 'LLMs'. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' or 'deep_research', which may have overlapping use cases.

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

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

The description gives clear context on when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains optional parameters and their requirements, such as the API key for Anthropic. However, it does not explicitly mention when not to use the tool or suggest alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining internal routing across 4,552 tools and 1,160 sources, and returns structured answers with pipeworx:// citation URIs. 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 verbose, listing many examples, use cases, and alternative tools. While it front-loads with 'PREFER OVER WEB SEARCH', it could be more concise by trimming redundant examples and guidance already covered in annotations.

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 (6 params, all documented), the description provides sufficient context: explains the tool's scope, typical queries, expected output format, and relationship to sibling tools. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters described (including aliases for 'question'). The description does not add new semantic details beyond what the schema provides. It mentions the question parameter and gives examples, but that's baseline when schema covers everything.

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

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

The description clearly states the tool answers factual questions using authoritative sources, with specific verb 'ask' and resource 'Pipeworx'. It distinguishes itself from siblings by explicitly preferring over web search and naming alternatives 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?

Provides explicit when-to-use guidance (factual questions, 'what is', 'look up', etc.) and when-not-to-use (for hallucination-resistant single answer use grounded, for broad multi-part use deep_research). Also says 'START HERE for most questions', making the default entry point 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 (readOnlyHint, etc.), description adds detail: extra LLM call, refusal reasons ('not_in_source', 'no_tool_match', etc.), return structure with answer, evidence, confidence, source, and fetched_at.

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 clear sections but slightly verbose (e.g., listing all aliases). Front-loaded with main purpose. Every sentence adds value, but could be 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?

Given the complexity of 4,552 tools across 1160 sources, the description fully explains the tool's usage, cost trade-offs, refusal mechanism, and return structure. No output schema but description compensates.

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 one required parameter and aliases. Description says 'Your question in natural language' which matches schema. No additional semantic value beyond what schema provides.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains it routes to the right tool, fetches data, and extracts answer using only tool results. It distinguishes from sibling ask_pipeworx by noting the extra extraction step.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts. Also advises preferring ask_pipeworx for casual lookups due to extra cost.

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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: market resolution, classification, parallel fan-out, evidence packet structure, market_match_confidence inspection, parent_event extraction, news fallback, short-circuiting on low confidence, closed market handling, wide-spread warnings, and cancellation rule parsing. This goes far beyond annotations.

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

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

The description is very long (multiple paragraphs) but well-structured with clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It packs a lot of information, but could be more concise. The length is justified by 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 covers return shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fields, safety mechanisms, and resolution-rule risk. It addresses edge cases like low confidence, closed markets, wide spreads, and cancellation rules, making it very complete.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description provides examples for market_input and explains depth options, but adds little 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 it researches Polymarket bets by pulling Pipeworx data, with specific examples of inputs and outputs. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the focus on comprehensive evidence packets is distinct.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...'), provides detailed classifiers, fan-out examples, and safety mechanisms. It also explains when results are blocked (low-confidence matches, closed markets), giving clear 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 indicate read-only, idempotent, non-destructive. Description adds context: pulls SEC EDGAR/XBRL data for companies, FAERS/FDA data for drugs, correct fiscal year handling. No contradictions.

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

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

Single paragraph, front-loaded with natural language triggers, then core purpose. Each sentence adds value. Could be slightly more structured but effective.

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

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

No output schema, but description explains returns paired data with citation URIs. Covers metrics for both types. Lacks exact output format but sufficient for agent to understand.

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

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

Schema coverage is 100%, but description adds meaning: explains what data is pulled per type (revenue, net income, etc., for companies; adverse-event counts, approval counts, trial counts for drugs) and that results are sorted by primary metric.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with natural language query examples. It distinguishes from sibling tools by explicitly preferring over sequential lookups.

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

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

The description explicitly states to prefer this tool over sequential lookups when comparing entities, and gives examples. It lacks explicit when-not-to-use but is clear on 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?

Discloses key behaviors: uses structured data only, not open-web; decomposes questions; returns findings with evidence, confidence, source, timestamps, and citations; explicitly reports gaps. Also mentions 15-60s response time and account/payment requirements. All consistent with readOnlyHint, idempotentHint, openWorldHint 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: account info first, then functionality, then usage guidance, then timing. Every sentence is informative and earns its place. Minor redundancy (e.g., 'this is NOT open-web search' is emphasized but important).

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 the return structure (findings packet with evidence, confidence, source, citations, gaps). It addresses prerequisites, alternatives, and expected performance. Slight lack of detail on error handling, but overall complete for this complex tool.

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

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

Schema coverage is 100% but the description adds extra meaning: for 'question' it explains 'Broad/multi-part is fine — decomposition is the point'; for 'depth' it details the number of facets per option and that 'thorough' requires a paid plan. This goes beyond the schema's minimal description.

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

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

The description clearly states 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources...' and distinguishes from siblings like ask_pipeworx for single lookups and breaking news. It specifies the tool's unique capability of decomposing questions into facets and parallel tool routing.

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 this tool: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account requirements and the alternative ask_pipeworx for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results include full input schemas with examples and are ready to call directly, enhancing transparency 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?

The description is front-loaded with the core purpose and uses multiple sentences that each add value: usage guidance, domain examples, return format, and when to call. It is arguably slightly verbose but still effective 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?

There is no output schema, but the description compensates by clearly specifying the return format: 'top-N most relevant tools with names, descriptions, and full input schemas... ready to call directly.' This is sufficiently complete for a discovery tool, though pagination details are omitted.

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 the schema itself documents all 6 parameters. The description explains that `query` accepts natural language and lists aliases, but adds no significant new meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Find tools' and the resource 'by describing the data or task,' distinguishing it from sibling tools like 'deep_research' or 'validate_claim' which are more specific. It also lists a broad range of domains, reinforcing its role as a discovery 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 says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context and when to use, though it lacks explicit alternatives or when-not-to-use scenarios.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are present. The description adds behavioral details: parallel fanned-out calls across multiple sources, specific output fields (cik, company_name, filings, fundamentals, patents, news, LEI), a future sunset for patents (soft-fails after May 2025), and fallback logic (GDELT→GNews). No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads example queries and purpose. It contains all necessary information but could benefit from bullet points or clearer structuring for easier scanning. Length is 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 the tool's complexity (multiple sources, many outputs) and lack of output schema, the description covers inputs, outputs, limitations, and usage preferences. It lists returned fields but not in a structured format. Reasonably complete but could provide explicit output 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% with descriptions for both parameters. The description adds meaningful context: explains 'value' can be ticker or zero-padded CIK, reinforces that names are unsupported, and notes 'type' is currently limited to 'company'. This adds value beyond schema alone.

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

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

The description clearly states the tool's purpose as a 'full cross-source profile of a US public company' with specific examples like 'Tell me about X' and lists the data sources (SEC, XBRL, USPTO, etc.). It differentiates from sibling tools like resolve_entity by noting that names are not supported, requiring prior use of resolve_entity.

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 instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Specifies acceptable inputs (ticker or CIK) and warns that names are not supported, directing users to resolve_entity first. Clear when-to-use and 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 destructiveHint=true and idempotentHint=true. Description adds minimal behavioral context beyond stating 'Delete' and 'clear sensitive data'. No additional details on consequences, permissions, or irreversibility.

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: first states purpose, second provides usage context and sibling references. 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 single required parameter and annotations covering destructiveness/idempotency, description is fairly complete. Lacks return value info but acceptable for a deletion tool.

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

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

Schema description coverage is 100% for the single parameter 'key'. Description adds no additional meaning beyond 'by key'. Baseline 3 as schema already documents sufficiently.

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 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory by key). Distinguishes from siblings like 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Mentions pairing with remember/recall but does not explicitly state when not to use.

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

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

Description discloses fetching, extracting title/description/key links, and emitting standard format. Aligns with annotations (readOnlyHint, idempotentHint, not destructive). No mention of rate limits or auth, but adequate.

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 functional sentences plus a bullet-like list of uses. Efficient but could be tighter. 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 two params, no output schema, and strong annotations, the description covers purpose, process, and outcome fully. Includes explicit output format 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 description coverage is 100%, so baseline 3. Description adds no extra meaning beyond what schema already provides (e.g., default/max values are in schema).

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource. Distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation.

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

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

Explicit use cases are listed (getting client's site indexed, drafting for own project, auditing competitor). Lacks explicit when-not-to-use, but context from siblings is sufficient.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are already clear. The description adds the return fields, confirming the tool's scope. No contradiction. For a read-only tool with rich annotations, this is sufficient.

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

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

The description is a single sentence that front-loads the purpose and lists return items. Every word is meaningful; no waste. Excellent structure.

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 low complexity (1 param, rich annotations, output schema present), the description adequately covers what the tool does and returns. It could mention potential error cases, but that is not critical for correct 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% for the single parameter 'id', with a description. The tool description briefly restates 'by its package ID', adding no new semantic value beyond the schema. Baseline score of 3 applies.

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

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

The description clearly states the action ('Get full metadata') and the resource ('HealthData.gov dataset'). It distinguishes from sibling 'search_datasets' by specifying that it uses a package ID and returns full metadata. The listed return fields add specificity.

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 'by its package ID (returned by search_datasets)', which implies a usage sequence. Though it does not explicitly state when not to use, the context is clear enough for basic 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 read-only, idempotent, non-destructive. Description adds that it lists active subscriptions by default and lists specific return fields, which is useful context beyond annotations.

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

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

Two concise sentences front-load key info: what it does, return fields, and a usage example. No wasted words.

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

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

Despite no output schema, description explicitly lists return fields. Default behavior (active only) is stated. With annotations covering safety, this is fully complete for a list tool.

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

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

Schema coverage is 100% with parameter description. Description adds no additional parameter detail beyond what schema provides, so baseline 3 is appropriate.

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

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

Clear verb+resource (list subscriptions), specifies return fields and default scope (active). Distinguishes from sibling tools subscribe/unsubscribe.

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

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

Explicitly states when to use: review monitoring before adding subscriptions or find an id to cancel. Provides actionable 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?

Discloses rate limit (5 per identifier per day), cost (free, no quota impact), and impact (roadmap influence). No contradiction with annotations (all false).

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

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

Front-loaded with main purpose, each sentence adds value (usage, instructions, restrictions). No redundancy, efficient length.

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

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

Given 3 params (2 required, nested objects) and no output schema, the description covers purpose, usage, constraints, and parameter guidance comprehensively.

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 valuable usage tips for message (be specific, 1-2 sentences) and context (which tool/pack/vertical), earning a 4.

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 via action verbs ('Tell'), lists specific use cases (bug, feature/data_gap, praise), and distinguishes it from siblings like ask_pipeworx by focusing on feedback submission.

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

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

The description explicitly states when to use (e.g., wrong data, missing tool, positive experience) and what to avoid (don't paste end-user prompt), providing clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: caching behavior (5min-1h), data source (CF analytics-engine), and no PII.

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 (~5 sentences), front-loads the core purpose, and every sentence adds value. No redundancy or fluff.

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

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

Given the simple tool (1 optional parameter, no output schema), strong annotations, and full schema coverage, the description provides complete context: purpose, usage, behavioral details, and data characteristics.

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 covers the window parameter's enum values fully. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This 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?

The description clearly states the tool returns top tools, packs, and total call volume over recent windows, which is distinct from sibling tools like ask_pipeworx or discover_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?

Description lists three specific use cases (discovering hot data, confirming canonical choice, aligning use cases) but does not explicitly state when not to use it or compare with 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 indicate read-only, non-destructive, idempotent behavior. The description adds extensive behavioral context: explains the algorithms (monotonicity, partition checks), the semantic anchor (Jaccard similarity), partition filter, response structure, and fill check analysis. 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 and well-structured with clear sections and examples. It effectively uses bold for emphasis. While slightly verbose, every sentence adds value, and the structure aids readability.

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

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

Despite no output schema, the description fully explains the response format (opportunities array with fields, partition check details) and the fill check logic. It covers edge cases (low similarity, placeholder filters) and references a sibling tool for further action. Comprehensive for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the modes, providing examples of valid inputs (e.g., 'fed-decision-may-2026'), and clarifying the expected format (slug or URL). This additional context aids 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 that the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It explicitly distinguishes the three modes (no args for trending scan, event for specific market, topic for cross-event scan) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: no args for a general scan, event for a specific market, topic for cross-event scanning. It explains the advantage of cross-event mode and warns when not to trade based on fill check results. Also directs users to polymarket_fill_risk for custom sizing.

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?

Despite annotations already marking the tool as read-only and idempotent, the description goes far beyond by explaining caching (1h KV-level), output structure (segments, diagnostics), and detailed edge calculations (Kelly, slippage, model specifics). 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 comprehensive but lengthy. It is well-structured, starting with purpose, then detailing segments, parameters, and response. While every sentence provides value, some brevity could enhance readability without losing essential detail.

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

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

The description fully covers the tool's complexity, including return structure (by_segment, diagnostics) and edge computation. Since there is no output schema, the description compensates by explaining exactly what the agent can expect, making it complete for correct invocation and 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?

The input schema already provides 100% parameter coverage with descriptions. The description further enriches each parameter with behavioral context, such as the effect of min_liquidity on 'walking the book' and the interplay between min_kelly and partition leg kelly, adding significant 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 that the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is built for the question 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data-driven edges across three model families.

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

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

The description provides clear context for when to use the tool (daily edge discovery, avoiding paging hundreds of markets) and details filtering knobs. However, it does not explicitly exclude use cases or contrast with sibling tools like polymarket_arbitrage, leaving some ambiguity for an agent deciding between similar tools.

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

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

The description goes well beyond annotations by detailing output structure (tracked, expired, snapshot_dates), explaining limits (60-day TTL, daily closes not intraday), and noting gaps due to cache-misses. It does not contradict any annotations.

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

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

The description is thorough and front-loaded with purpose. Each sentence adds useful information, though it could be slightly more concise without losing detail.

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

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

Given the tool's complexity and absence of output schema, the description fully covers the output format, limitations, and data interpretation. It addresses potential user questions about data availability and decay computation.

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

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

Schema coverage is 100%, but the description adds extra context like 'snapshot family' for window and clarifies default values and constraints. This provides meaningful additional 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 clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from siblings like polymarket_edges by being a derived analysis 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 explains when to use the tool to differentiate between fresh and old edges, providing context like 'a 3-week-old wide edge is a different trade.' However, it does not explicitly mention when not to use it or name 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: walks the order book ladder, computes fill scenarios, returns verdicts (clean|degraded|cannot_fill), and warns about thin legs and forced directional risk. This exceeds 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 moderately long but well-structured with sections for single-market and basket modes. It front-loads the main purpose and uses clear formatting. A minor deduction for some redundancy (e.g., repeating 'shares per leg' in basket mode) but overall efficient.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is highly complete. It lists all key outputs, provides usage constraints, and explains the risk of partial fills. No significant gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100% but the description adds significant meaning beyond the schema. It explains each parameter's role in single-market vs basket mode, default values, clamping ranges, and the auto-detection logic for side in basket mode. This enriches the semantics substantially.

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, distinguishing between single-market and basket modes. It lists specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains risks of not using it (theoretical overround not capturable, partial basket fills leading to unhedged positions) and specifies required parameters ('REQUIRES one of market or event').

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 extensive behavioral traits including compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for skipped comparisons. This goes well beyond the readOnlyHint and destructiveHint annotations, which only indicate safety and non-destructiveness.

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 information-dense and well-structured with clear sections for modes, response, and safety fields. Though slightly verbose, every sentence serves a purpose and the critical details are front-loaded.

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

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

Given the complexity and lack of output schema, the description covers key aspects: leg prices, spread computation, compatibility warnings, temporal alignment, and skipped comparisons. It is thorough enough for an agent to understand expected outputs and edge cases, though an explicit output structure would complete 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?

The input schema covers 100% of parameters with descriptions, but the tool description adds significant meaning: it explains the two modes (topic vs explicit), provides example topic values, and clarifies how explicit parameters override topic-mapped ones. This adds value beyond the schema alone.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same question. It names the two venues and the specific metric (spread), distinguishing it from siblings like polymarket_arbitrage which focus on single-venue opportunities.

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

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

The description implies usage for comparing prices across venues but does not explicitly describe when to prefer this tool over alternatives like polymarket_arbitrage or polymarket_edges. There is a caution about many topics returning warnings, but no clear when-to-use / when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping details (identifier-based) that go beyond annotations, providing valuable behavioral context without contradictions.

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

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

The description is concise (4 sentences) with no wasted words. Each sentence provides essential information: purpose, usage examples, scoping, and pairing with related tools.

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 simple input (one optional parameter) and no output schema, the description fully covers both behaviors (retrieve by key, list all), scoping, and the tool's place in the ecosystem with remember and forget.

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

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

Schema coverage is 100%, with the schema already explaining the 'key' parameter and that omitting it lists all keys. The description reinforces this but does not add significant new semantic meaning.

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 value saved via remember or lists all keys when no argument is given, using specific verbs and identifying the resource. It distinguishes from siblings like remember and forget.

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

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

Provides clear context on when to use (to look up previously stored context) and mentions alternatives (remember, forget). However, it does not explicitly state when not to use or list all alternative retrieval methods.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return fields (source, citation_uri, raw payload) and the side effect of the 'mark_read' parameter, which affects subsequent calls. This goes beyond the annotations without contradicting them.

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

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

The description is one coherent paragraph of about five sentences, front-loaded with the core purpose, followed by key details and an alternative access note. Every sentence adds value without redundancy or filler.

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

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

The description covers return fields, key filters (type, since), and the mark_read behavior. However, it omits mentioning the 'limit' and 'unread_only' parameters present in the schema. Since there is no output schema, the description should ideally summarize all parameters. The return value description is adequate but incomplete regarding all filtering options.

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

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

All five parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description goes beyond by providing examples (e.g., type 'sec_8k') and explaining the behavior of 'mark_read' and 'since' as an ISO timestamp, adding practical meaning for an AI agent.

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

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

The description clearly states the tool retrieves recent alerts from a subscription feed, specifying return fields and filtering options. However, it does not explicitly distinguish this tool from sibling tools like 'recent_changes' or 'subscribe', though the specific content type (alerts) provides some differentiation.

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

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

The description mentions that polling works fine and provides an alternative access method via a URL, which implies appropriate use cases. However, it does not provide explicit guidance on when to use this tool versus related siblings, such as 'recall' or 'list_subscriptions', 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 indicate readOnly, openWorld, idempotent, not destructive. The description adds source details, fallback behavior, USPTO soft-fail status, and return format (changes, total_changes, URIs), providing 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?

The description is a single paragraph but tightly written with examples and fallback details. It could use more structure (e.g., bullet points), but every sentence is informative and earns its place.

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

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

Given the complexity of multi-source fan-out, the description covers all necessary context: sources, fallback, parameter semantics, and return format. No output schema exists, so the description adequately explains what the tool returns.

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

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

Schema coverage is 100%, so parameters are documented. The description adds value by clarifying 'since' accepts ISO or relative shorthand with examples, and 'value' can be ticker or CIK, enhancing 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?

The description clearly states the tool provides a change feed for a company over a window, fanning out to SEC, GDELT/GNews, and USPTO. It distinguishes from sibling tool entity_profile by specifying when to use the static profile instead.

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 example queries are given, along with when to use entity_profile. The description explains fallback behavior (GDELT preferred, GNews on rate limit/5xx) and parameter usage for 'since'.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds useful behavioral context: scope by identifier, persistence (authenticated vs anonymous 24h), and implicit idempotency support. 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?

Five sentences, each adding distinct value: purpose, usage, scope, persistence, sibling pairing. No redundancy, front-loaded with core function.

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 2-parameter tool with no output schema, the description is remarkably complete, covering purpose, usage, behavior, parameters, and context. 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 clear descriptions. The description adds extra meaning by providing example key formats and explaining the key-value pair scope. This adds value beyond the schema.

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

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

The description clearly states the verb 'save' and resource 'data' for reuse, distinguishing it from siblings like recall and forget. It explicitly says 'Save data the agent will need to reuse later' and contrasts with retrieve and delete.

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and suggests pairing with recall and forget. It does not explicitly state when not to use but provides enough context for correct usage.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. It details the return format for each entity type, including specific fields and citation URIs. This is transparent about the internal process and output structure.

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 well-structured: it opens with example queries, gives usage guidance, then enumerates supported types with specific outputs. It is around five sentences with no redundant information, making it easy to scan and understand.

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

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

Given the tool's complexity (two entity types, multiple output fields, cascading lookups), the description is quite complete. It explains what is returned for each type and provides citation info. However, it does not mention error handling (e.g., what happens if no match found) or edge cases. The absence of an output schema is compensated by the description's detail. Overall, it is very thorough but could be slightly more complete.

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

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

With 100% schema description coverage, the description still adds meaning beyond the schema. It provides concrete examples for the 'value' parameter (e.g., 'AAPL', 'ozempic') and explains how the output differs per entity type. The schema defines type as enum and value as string with a brief description, but the description enriches understanding with usage patterns and expected outputs.

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's purpose: resolve user-spoken names to canonical identifiers for company or drug entities. It uses specific verbs and resources (e.g., 'resolve to ticker + CIK + company_name') and distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.' The examples and supported types provide unambiguous purpose.

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

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

The description explicitly states when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It provides example queries that trigger the tool. However, it does not explicitly mention when not to use it or compare with alternatives like entity_profile, though the sibling list hints at other 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, openWorldHint, and destructiveHint false. The description adds that it internally calls ai_visibility_check, ranks results, and returns score, confidence, and signal density. This provides 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?

The description is extremely concise: two sentences for main purpose, one for example, and one for return value. No wasted words, front-loaded with key information.

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

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

Given 4 parameters and no output schema, the description covers purpose, behavior, output format, and relationship to sibling tool. It mentions required conditions for anthropic API key. Almost complete; could explicitly state that it's an aggregation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the entities array's special role (first entry as subject for narrative) and the overall output format. This ties parameters together and adds 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's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and action (probes, ranks, surfaces). It distinguishes itself from sibling tool ai_visibility_check by implying it aggregates multiple entities.

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 implies this tool is for comparison, contrasting with ai_visibility_check for single entities. However, it lacks an explicit 'when not to use' statement.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds critical behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' Also details return structure (summary block, advisories, links, versions). 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?

Description is about 5 sentences, front-loaded with the core purpose, well-structured with parentheses and dashes for readability. Every sentence adds value, no 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?

Despite no output schema, description fully explains what is returned: summary block fields (is_latest, license, etc.), per-advisory detail, links, alternative versions. Also covers failure modes and timing. For a two-param tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds little beyond schema for parameters: it mentions scoped packages and version defaults, but these are already in schema descriptions. The composite behavior is explained but not tied closely to parameters.

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

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

Description starts with a clear, specific verb+resource combo: 'Composite "should I add this npm package to my project" check in ONE call — fans out across deps.dev (license + advisories + version history) and bundlephobia'. It explicitly distinguishes from siblings by mentioning it's a composite check and limiting to NPM ecosystem in v1.

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 exact use cases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also gives exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Provides clear when-to and when-not-to 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe, idempotent read operation. The description adds value by specifying the data source (HealthData.gov) and return fields, providing behavioral context beyond annotations. It does not contradict annotations.

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

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

One sentence, well-structured, with examples and key information front-loaded. No redundant phrases. Every sentence earns its place.

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

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

With an output schema (not shown), annotations covering safety and idempotence, and a description that specifies source and return fields, the tool definition is complete. It addresses complexity of a search tool without missing critical details.

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%: both 'query' and 'limit' have detailed descriptions with examples and range. The description adds little beyond the schema (e.g., 'by keyword' is already implied). Baseline of 3 is appropriate when schema fully documents parameters.

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

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

The description clearly states the tool searches HealthData.gov for public health datasets by keyword, with examples like 'COVID hospitalizations'. It specifies the return fields (titles, descriptions, organizations, resource links). This distinguishes it from sibling tools like 'get_dataset' (which retrieves a specific dataset) and 'search_within' (which might search within a dataset).

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

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

No explicit guidance on when to use this tool versus alternatives like 'deep_research' or 'search_within'. The description provides examples but does not state exclusions or prerequisites. It implies usage for searching HealthData.gov but lacks 'when not to use' or comparisons 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 readOnly and idempotent, but the description adds critical behavioral details: embeddings model (BGE-base-en), windowing (500-char overlapping), similarity metric (cosine), max input size (200K chars) with truncation flagging. This fully discloses internal workings and limits beyond annotations.

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

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

The description is two well-structured sentences covering purpose, use case, technical details, and integration. Every sentence adds value; no redundant or verbose phrases. Front-loaded with key semantic search context.

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

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

Given no output schema, the description sufficiently explains return format (passages, offsets, similarity scores). It covers usage boundaries (200K chars), integration with ask_pipeworx_grounded, and technical method. Complete for a semantic search tool with 3 parameters and rich annotations.

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

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

Schema coverage is 100% with clear descriptions for text, query, and limit. The description reinforces these but adds little new meaning (e.g., rephrasing 'natural-language query'). It does include the 200K char cap, which is also in the schema. Baseline 3 is appropriate as the description does not significantly augment the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC filings. It distinguishes from sibling tools by mentioning 'Pairs with ask_pipeworx_grounded' and emphasizes the value of returning passages with offsets, making its unique purpose evident.

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 big to cram into the prompt.' It also describes how to pair with ask_pipeworx_grounded for grounding. However, it does not explicitly list situations where other sibling tools (like deep_research) might be preferable, so it lacks thorough exclusion criteria.

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

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

The description adds behavioral context beyond annotations: it requires OAuth, details delivery channels (feed always on, optional email/sms/webhook), specifies SMS rate limits (10/day), and explains webhook signing. However, it lacks clarification on idempotency (annotation says true but description suggests new subscription each time) and doesn't mention if duplicate subscriptions are allowed.

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

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

The description is well-structured, front-loading the main action and then detailing types and delivery. While slightly verbose, each sentence provides value. Minor improvement could be condensing type descriptions.

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 (3 parameters, nested objects, no output schema), the description covers auth, delivery, type-specific params, and constraints. It mentions return of subscription id but does not explain idempotency or duplicate behavior, leaving minor 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 coverage is 100%, and the description enriches each parameter with examples and explanations (e.g., sec_8k items codes, polymarket_edge topic, delivery constraints). This adds significant 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 action ('Create a proactive monitoring subscription'), identifies the resource ('live-data event stream'), and distinguishes it from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation and proactive monitoring.

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 context for when to use the tool (creating subscriptions) and includes prerequisites (OAuth account, phone verification for SMS). However, it does not explicitly state when not to use it or mention alternatives like 'recent_alerts' for pulling events.

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: describes return content (category-bucketed examples with tool shapes), source (live catalog of thousands of tools), and focus mechanism (topic). 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 long but front-loaded with common user queries. Every sentence adds value, though some redundancy exists (e.g., listing all categories twice). Could be 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?

Given no output schema, description adequately explains return format (category-bucketed questions with tool shapes). Covers what the tool does, how to call it, and what to expect, making it complete for a discovery tool.

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

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

Schema coverage is 100% and description adds value by listing example topic values and clarifying behavior when omitted (full spread), which goes beyond the schema's generic description.

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

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

Uses specific verb+resource ('returns category-bucketed example questions') and distinguishes from siblings by stating it's the onboarding entry point and mentioning meta-tools like ask_pipeworx.

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: 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains optional topic argument to focus. Lacks explicit when-not-to-use 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?

Discloses that the row is deactivated, not deleted, preserving historical data—a behavioral trait beyond annotations. Annotations already indicate non-destructive and idempotent, but the description adds meaningful context without contradiction.

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

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

Two concise sentences with no wasted words. The core purpose is front-loaded, and all information is relevant.

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 simple single-parameter tool with annotations and no output schema, the description is sufficiently complete. It explains the effect and a key constraint, though it could mention error handling or prerequisites.

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 does not add extra meaning for the single 'id' parameter beyond what the schema provides.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), effectively distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on when to use the tool. However, it does not state when not to use it or suggest alternatives.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details the data source (SEC EDGAR + XBRL), return format (verdict, structured form, citation, delta), and notes it replaces multiple sequential calls, offering rich behavioral context.

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

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

The description is a single paragraph that is informative but slightly verbose. It could be more structured with bullet points, but it remains concise and covers key aspects without redundancy.

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

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

Given the single parameter, comprehensive annotations, and no output schema, the description fully explains the tool's function, domain, source, return values, and efficiency benefits, making it complete for an agent.

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

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

With 100% schema description coverage, the schema already describes the 'claim' parameter well. The description adds examples and additional context but does not significantly enhance beyond the schema, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples like 'Is it true that…' and 'fact check', and narrows the domain to company-financial claims, distinguishing it from sibling tools.

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

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

The description advises using the tool whenever the agent needs to fact-check a claim, and specifies the domain of company-financial claims. It does not explicitly mention alternatives but provides clear context for appropriate use.

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