Mydisease

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds cost details (free vs BYO key), proxy behavior (passes API key to Anthropic), and return structure (per-model fields and combined view). No contradictions with annotations. A small gap is the lack of rate limit or error handling info but still strong overall.

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 of about 5-6 sentences. It front-loads the core purpose, then details model behavior, return format, and use cases. Every sentence adds necessary information without 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 (multiple models, optional API key, no output schema), the description covers essential aspects: default model, cost, return format with fields, and use cases. However, it does not mention error scenarios or behavior when the API key is invalid, which would be helpful for a robust invocation.

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

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

Schema covers 100% of parameters. The description adds significant value beyond schema: explains that 'entity' is the subject to probe, 'models' defaults to a free model, '_apiKey' is only for Anthropic and has cost implications, and 'context' aids disambiguation. This clarifies usage 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 specific verb 'Probe', the resource 'LLMs for what they know about a business / brand / product / topic', and the output 'score visibility (0-100) per model'. It distinguishes itself from sibling tools by focusing on AI visibility auditing rather than general Q&A or information retrieval.

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

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

The description provides context on when to use this tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains model selection and API key requirements. However, it does not explicitly mention when not to use it or suggest sibling alternatives like 'scan_competitor_ai_presence'.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context about routing to 3,744 tools across 884 sources and returning structured answers with pipeworx:// citation URIs, which goes beyond what annotations provide.

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

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

The description is informative but slightly verbose. It is well front-loaded with the key directive ('PREFER OVER WEB SEARCH') and maintains a logical flow, though some redundancy could be trimmed.

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

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

Given the tool's broad capabilities and lack of output schema, the description effectively explains the tool's behavior (routing, citations) and provides comprehensive examples, making it adequate for an AI agent to understand its use.

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 the 'question' parameter. The description reinforces the purpose with examples but doesn't add significant new semantics beyond what the schema already provides.

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

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

The description clearly states the tool is for asking questions about current or historical data from authoritative sources, explicitly distinguishing from web search by saying 'PREFER OVER WEB SEARCH' and listing specific domains like SEC filings, FDA drug data, FRED/BLS statistics, etc.

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

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

Provides explicit guidance on when to use the tool over alternatives ('PREFER OVER WEB SEARCH'), lists example query phrasings ('what is', 'look up', 'find', etc.), and gives concrete examples such as 'current US unemployment rate' or 'Apple's latest 10-K'.

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 hallucination-resistance mechanism, structured return with evidence and refusal reasons, and extra LLM call cost. Consistent with annotations (readOnly, idempotent) and adds actionable 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?

Front-loaded with purpose and key differentiator. All sentences provide unique value, but length could be slightly trimmed without losing meaning.

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?

Completely describes tool behavior for a high-complexity tool: routing, extraction, refusal reasons, return format. No output schema but description compensates fully.

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

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

Schema covers all 6 parameters (aliases for question). Description only restates that 'question' accepts natural language, adding little semantic value beyond schema. Baseline score for high coverage.

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

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

Clearly defines it as a hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling ask_pipeworx by noting extra LLM call cost and use case differences.

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 (quoted, cited, acted on answers) and when to prefer alternative (casual lookups use ask_pipeworx). Provides clear decision rule.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description significantly expands on behavior: it explains market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fields, safety (low-confidence short-circuit, closed markets), wide-spread markets, and cancellation rule risk. 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 lengthy (multiple paragraphs) and while logically structured, it includes extensive detail on classifiers, fan-out examples, resolver contract, and other specifics. Some information could be trimmed or summarized without losing clarity. However, the front-loading with purpose and usage is effective.

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

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

Given the tool's complexity (3 parameters, no output schema, many behavioral aspects), the description is remarkably comprehensive. It covers how to interpret results (market_match_confidence, parent_event, news fields), handles edge cases (low confidence, closed markets, wide spreads), and provides cancellation rule guidance. The lack of output schema is fully compensated by detailed field descriptions.

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 parameters are already documented. The description adds value by listing examples for market_input, explaining depth options ('quick = 2-3 evidence sources, thorough = full fan-out'), and detailing include_raw behavior ('summarized to few fields' vs 'full upstream payloads'). This enhances the schema but does not replace it.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and output (evidence packet + comparison). The description distinguishes this from siblings like polymarket_edges and ask_pipeworx by focusing on a single bet research with category-specific fan-out.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also implies when not to use by noting closed/dead markets short-circuit and low-confidence matches suppress analysis. However, it does not explicitly list alternatives or provide when-not-to-use scenarios, leaving some room for ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 dense but well-structured, starting with natural language patterns, then data source details, then result format. Every sentence adds value, though it could be slightly more front-loaded with the core action.

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

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

Given no output schema, the description explains that returns include 'paired data + pipeworx:// citation URIs per entity' and that results are sorted by primary metric. However, it lacks details on the exact structure of the paired data (e.g., key-value pairs, order). This minor gap prevents a higher score.

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 meaningful context: explains what each type pulls (revenue, net income, cash for companies; adverse-event counts, FDA approvals for drugs) and provides examples for values (tickers/CIKs for companies, drug names). This goes beyond the schema's enum descriptions.

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

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

The description clearly specifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes from siblings like entity_profile by emphasizing parallel comparison 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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries (e.g., 'which is bigger / better'). While it doesn't explicitly state when not to use it, the guidance is strong and context-rich.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds process details (decomposition, parallel, extraction), output format (structured findings, gaps), and expectations (15-60s, account required). No contradiction.

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

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

Description is well-structured with clear sections (main capability, process, usage, requirements, time). Each sentence adds value, but slightly verbose; could be tightened without loss.

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 comprehensively covers inputs, process, outputs (structured findings, gaps, citations), requirements, and timing. It provides all needed context 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%, but description adds value: for 'depth' explains enumeration values (quick=3, etc.) and paid plan requirement; for 'question' clarifies broad/multi-part is fine. This enriches understanding beyond schema.

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

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

The description clearly states 'Grounded multi-source research in ONE call' and explains the decomposition, parallel routing, and extraction process. It distinguishes from sibling 'ask_pipeworx' by noting the latter is for single 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?

Explicitly says 'Use for broad or multi-part questions' with examples, and 'use ask_pipeworx for single lookups'. Also mentions prerequisites (Pipeworx account, paid plan for 'thorough').

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, destructiveHint=false. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly. This adds functional behavior context without contradicting annotations.

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

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

The description is well-structured, front-loading purpose and then providing usage context and return value. It is slightly lengthy but every sentence adds value. Could be trimmed slightly 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 (aliases, 6 params), schema covers everything, and description adds usage guidance and return details (names, descriptions, schemas). No output schema exists, but description sufficiently explains what is returned.

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 well documented. Description reinforces aliases and provides natural language examples. For limit, it adds default and max values, which goes 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 finds tools by describing data or task, and distinguishes itself from siblings by emphasizing it's for browsing/discovering available tools. It says 'Call this FIRST when you have many tools', which sets clear purpose and usage context.

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

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

The description explicitly says when to use: when needing to browse, search, look up, or discover what tools exist for specific domains. It suggests calling it first. However, it doesn't explicitly state when not to use (e.g., if you already know the tool), so it's clear but not fully exhaustive.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful context about data sources (MONDO, DisGeNET, HPO, CTD), which goes beyond annotations. No contradictions.

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

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

Clear and front-loaded with core action. The bullet list of data sources could be integrated into prose for slightly better conciseness, but every sentence adds value and the overall structure is good.

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?

Lacks output schema, and description does not detail the return structure (e.g., JSON keys). Lists data sources but doesn't explain how fields parameter values map to outputs. Adequate but with gaps given tool complexity.

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

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

Schema description coverage is 100%, but description adds value by providing examples and accepted formats for 'id' and clarifying 'fields' parameter behavior (comma-separated, default all). This supplements the schema meaningfully.

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

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

The description clearly states the tool fetches the full aggregated annotation object for a single disease ID, specifying accepted ID formats (MONDO, DOID, OMIM) and data sources. It distinguishes from sibling tool 'query' for name resolution.

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

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

Explicitly advises to use 'query' tool first to resolve name to ID, implying when not to use this tool. Does not list other sibling alternatives, but the context is clear for the intended use case.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies the patent feature will soft-fail after May 2025, and explains the fallback from GDELT to 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 front-loaded with example queries, which is effective. It then packs many details. Every sentence adds value, but it could be slightly more concise by avoiding redundancy (e.g., 'full cross-source profile' is later expanded). Still highly functional.

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, so the description compensates by thoroughly listing return fields (cik, company_name, recent_filings with URIs, fundamentals with specific metrics, patents, news, LEI) and noting the patent deprecation and fallback. This gives a complete understanding of the tool's behavior.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'value' parameters. The description adds beyond schema by clarifying that 'type' is restricted to 'company' for now and that 'value' accepts ticker or zero-padded CIK, while reiterating that names are not supported. This adds useful nuance.

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

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

The description uses specific verbs like 'profile' and 'research' alongside examples ('Tell me about X', 'brief me on Tesla') and clearly states the output is a 'full cross-source profile of a US public company.' It distinguishes from sibling tool 'resolve_entity' by noting that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises to use 'resolve_entity' first if the user only has a name. This provides 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 declare destructiveHint=true and idempotentHint=true. The description adds minimal context ('by key') but does not disclose behaviors like what happens if the key does not exist or whether it returns a confirmation. With annotations present, this is adequate but not rich.

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), front-loads the primary action, and every sentence adds value. There is zero wasted text.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, and sibling relationships. However, it could briefly mention return value or error behavior to achieve full completeness.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description does not add any additional meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the verb 'Delete', the resource 'previously stored memory', and the method 'by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by mentioning them for pairing.

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with siblings, but lacks explicit when-not conditions.

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 fetches the page, extracts title/description/key links, and emits standard markdown. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description supplements without contradiction.

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

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

The description is concise (3 sentences), front-loaded with purpose, followed by behavior, output, and use cases. Every sentence adds value with no wordiness.

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 only 2 parameters, no output schema, and rich annotations, the description completes the picture: it explains input, process, output format, and practical applications. No gaps identified.

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 both parameters (url and max_links). The description mentions the URL but does not add details about max_links beyond the schema. Baseline is 3 as schema does the heavy lifting.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file', and distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence by specifying its unique output and use cases.

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

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

The description provides clear use cases (indexing client sites, drafting personal projects, auditing competitors) but does not explicitly exclude alternatives or mention when not to use this tool. It implies context but lacks direct comparisons.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. Description adds return structure and default filter to active subscriptions, exceeding 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: first states action and output, second provides usage guidance. No wasted words, 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?

Tool is simple with one optional param and no output schema. Description fully covers purpose, output fields, and usage, sufficient for correct agent invocation.

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

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

Schema coverage is 100% and parameter description already explains include_inactive. Description adds no new semantic meaning beyond schema.

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

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

Clearly states it lists the caller's active subscriptions, enumerates returned fields, and distinguishes from subscribe/unsubscribe via sibling context.

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

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

Explicitly advises using before adding subscriptions or to find an ID to cancel, providing clear when-to-use guidance; lacks explicit when-not-to-use but is implied.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds specifics about returned content (source versions, document counts) but does not disclose additional behavioral traits like potential performance or data freshness. 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?

A single, concise sentence that front-loads the core purpose ('Dataset statistics and release metadata') and specifies the target resource and examples. No wasted words.

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

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

Despite no output schema, the description adequately explains what the tool returns (source versions, document counts). For a simple metadata tool with no parameters and strong annotations, this is complete enough.

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

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

There are no parameters, and schema coverage is 100%. The description does not need to add parameter details. Baseline for zero parameters is 4, and the description does not detract.

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 'Dataset statistics and release metadata for MyDisease.info (source versions, document counts)', using a specific verb ('provides') and resource ('MyDisease.info metadata'). This distinguishes it from sibling tools like 'disease' or 'entity_profile' which focus on individual 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 implies usage for obtaining dataset statistics or release info, but does not explicitly state when to use this tool versus alternatives or when not to use it. Given sibling tools cover varied domains, additional guidance would be beneficial.

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 key behaviors beyond annotations: rate-limited to 5 per identifier per day, free usage, no quota consumption, and that the team reads digests daily for roadmap impact. There is no contradiction with annotations (which correctly do not mark it read-only or idempotent).

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

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

Every sentence serves a purpose: identifying the action, specifying when to use each type, giving formatting advice, and noting constraints. The structure is front-loaded with the core verb, followed by usage scenarios, then limitations. No wasted words.

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

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

Given the tool's simplicity (no output schema), the description covers all essential aspects: what feedback is, how to structure it, constraints (rate limit, quota), and what happens after submission (digests, roadmap impact). It is self-contained and leaves no major 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%, baseline 3. The description adds value by elaborating on the type enum (connecting each option to a concrete scenario), specifying message length guidelines (1-2 sentences, 2000 chars max), and clarifying the context object fields (pack, tool, vertical). This extra context justifies 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 submits feedback to Pipeworx (verb 'send', resource 'feedback'), and enumerates four specific feedback types (bug, feature, data_gap, praise) plus 'other'. It is distinct from sibling tools like ask_pipeworx or discover_tools, which serve different purposes.

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

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

Explicit guidance on when to use each feedback type: bug for wrong/stale data, feature for missing tools, data_gap for unavailable data, praise for positive experiences. The description also tells the agent what not to do ('don't paste the end-user's prompt'), providing clear boundaries.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds valuable context: it explains the data source ('CF analytics-engine'), states no PII is included, and reveals caching behavior ('Cached 5min-1h depending on window'). This fully complements the annotations without contradiction.

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

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

The description is four sentences, each adding unique value: first sentence defines purpose, second lists use cases, third provides behavioral details. It is front-loaded with the core functionality and contains no redundant or filler content.

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

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

Given the absence of an output schema, the description adequately outlines the return values (top tools, packs, call volume) and even hints at the data structure ('(pack, tool, count)'). However, it could be more explicit about the exact response format (e.g., list of objects) for complete clarity.

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

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

The input schema already describes the 'window' parameter with enum options and their semantics (shorter vs longer windows). The tool description reinforces this by mentioning the window values and adding context about caching duration, slightly increasing understanding beyond schema.

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

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

The description clearly states the tool returns 'the top tools, top packs, and total call volume' with a specific verb ('returns') and resource ('trending usage data'). It distinguishes itself from siblings like 'discover_tools' by focusing on real-time popularity signals rather than general discovery.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases) providing clear guidance on when to use. It does not cover when not to use or alternatives, but the positive guidance is strong.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds extensive behavioral details: internal checks (monotonicity, partition sum, Jaccard similarity threshold 0.30, placeholder filter, fill check with CLOB depth, theoretical vs realizable edge). No contradictions.

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

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

Description is long but well-organized: front-loaded with requirement, then mode explanations, then detailed checks. Every sentence adds value, though some could be trimmed without loss. Still appropriate given tool complexity.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array with fields, partition_check object, fill check results). Covers all important aspects: similarity anchor, placeholder filter, fill check with book depth. Complete 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 has 100% coverage with descriptions for both parameters. Description adds significant value by explaining what values look like (e.g., event slugs, seed questions) and how they affect behavior (single-event vs cross-event mode, internal processing).

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes two modes (event vs topic) and references sibling tools for fill risk, making the purpose specific and well-differentiated.

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 requires one of 'event' or 'topic', warns against calling with no args, and recommends event for specific markets and topic for cross-event scanning. Also notes cross-event catches patterns single-event misses, providing clear context for selecting the right mode.

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 provides extensive behavioral details beyond annotations: caching (1h at KV level), five model families, response structure (by_segment), edge calculations (edge_pp_net, Kelly fractions), slippage handling, diagnostics for empty segments, and special handling of Fed bets. It aligns with annotations (readOnlyHint true, idempotentHint true) and adds context without contradiction.

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

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

The description is lengthy (over 400 words) and densely packed with details. While every sentence adds value, it could be more concise. Front-loading the main purpose is good, but the volume may overwhelm some agents.

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 (9 parameters, no output schema, three model families), the description is exceptionally complete. It explains response structure, diagnostics (so agents understand empty segments), caching, and limitations (Fed data reliability). It compensates for the lack of output schema by detailing return fields like edge_pp_net, kelly_fraction, market.liquidity, etc.

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 9 parameters have good descriptions in the input schema (100% coverage). The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their interactive effects (e.g., min_partition_leg_kelly compensates for min_kelly not filtering partitions). This context helps agents understand parameter relationships beyond individual schema descriptions.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combination. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement rather than cross-market arbitrage.

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

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

The description includes explicit usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It details tradeable-edge knobs and filter options. However, it does not explicitly state when to use this tool versus alternatives like bet_research or polymarket_arbitrage.

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

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

The description goes well beyond the annotations (which confirm read-only, idempotent, non-destructive behavior) by detailing how data is sourced from daily snapshots, the response structure (tracked[], expired[], snapshot_dates[]), and limitations (60-day TTL, daily closes, not intraday). This provides rich behavioral context without contradiction.

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

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

The description is well-structured with a clear lead sentence, then answer illustration, then detailed response breakdown, then limits. While it is lengthy, every sentence contributes information necessary for a tool without an output schema. It is front-loaded with purpose. Slightly verbose but justified.

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 that there is no output schema and the tool returns a complex telemetry structure, the description fully compensates by explaining each response field (tracked[], expired[], snapshot_dates[]), including edge case notes (gaps, TTL, decay computation). This ensures an agent can understand the output without formal schema.

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

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

The input schema covers both parameters (days, window) with default values and allowed values. The description adds meaning: for 'days' it specifies 'lookback, default 14, max 30' (schema says clamp 2-30, but description adds 'max 30' context), and for 'window' it says 'snapshot family' and enumerates options. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges (raw snapshots) and polymarket_arbitrage by focusing on edge persistence over time.

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 evaluating edge persistence and decay, but does not explicitly state when to use this tool vs alternatives. It provides context ('a fresh wide edge and a 3-week-old wide edge are different trades') but lacks explicit guidance on when not to use or direct comparisons to sibling tools. This is adequate but not exemplary.

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 confirm readOnly, idempotent, non-destructive. Description adds detailed behavior: walks order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, forced_directional_risk). 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?

Well-structured with clear sections for single-market and basket modes. Starts with purpose, then REQUIRES, then details. Slightly verbose but every sentence adds value. Could be condensed slightly.

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?

Complex tool with 4 params, no output schema. Description covers return values thoroughly (top_of_book, vwap, slippage, verdict, etc.), edge cases (thin legs, forced directional risk), and practical implications. Complete for its complexity.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: explains size_usd interpretation for buys vs sells, default values, clamp range; side auto-default in basket mode. Clearly 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?

Description explicitly states the tool checks 'Realizable-vs-theoretical edge against live CLOB order-book depth', distinguishes between single-market and basket modes, and references specific use cases (before arb signals or edges > $500). Clearly differentiates from siblings 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 instructs to use before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains why theoretical overround is not capturable and partial fills convert arb into unhedged directional positions.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds rich behavioral context: it explains compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross-type/subtype counters. This reveals edge cases and failure modes that annotations alone cannot convey, fully meeting the transparency requirement.

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: a concise introductory sentence, followed by a breakdown of modes, response structure, and safety fields. Every sentence serves a purpose. While it is relatively long, the density of useful information justifies the length. Minor redundancy in the safety field explanation could be trimmed, but overall it is 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 (no output schema, multiple edge cases), the description is remarkably complete. It covers response format (leg-by-leg prices, spread array), all safety fields (compatibility_warning, temporal_alignment, skipped counters), and failure modes (non-equivalent shapes, semantic mismatch). An agent can confidently use this tool based solely on the description.

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 baseline is 3. However, the description adds significant value: it explains the two usage modes (topic vs explicit), clarifies that explicit parameters override topic mappings, and provides practical context (e.g., most pre-mapped topics currently return warnings). This extra meaning goes beyond the schema's role definitions.

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: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies the verb ('cross-venue spread'), the resources (two prediction markets), and distinguishes itself by focusing on the delta between venues. The two modes are explicitly described, making the tool's specific function unambiguous.

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

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

The description provides strong usage guidance: it explains the two modes (topic shortcuts vs explicit event pairings), notes that most pre-mapped topics currently return compatibility warnings, and clarifies when spreads are meaningful (temporal alignment, matched pairs). While it doesn't explicitly list alternative tools for similar tasks, the context about semantic mismatch and temporal alignment gives the agent clear criteria for when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by specifying return format (keyed by MONDO ID, best-matching keys) and query types. 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?

Concise, front-loaded with purpose, then usage, with examples. Every sentence adds value; 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?

Despite no output schema, description explains return format and covers typical use case. Sufficient for an agent to understand tool behavior and integrate with the 'disease' 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?

Input schema has 100% coverage with descriptions. Description adds value with concrete examples like 'diabetes' and 'mondo.label:asthma', clarifying fielded query syntax beyond the schema.

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

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

The description explicitly states it searches MyDisease.info for diseases by free-text or fielded query, returning matches keyed by MONDO IDs. It distinguishes from the sibling 'disease' tool by noting this tool resolves disease names before calling 'disease'.

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 guidance: use it to resolve disease names to canonical ontology IDs before calling the 'disease' tool. Examples of free-text and fielded queries illustrate usage. Lacks explicit 'when not to use' but context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the scoping mechanism and the dual behavior when key is omitted (list all keys). This goes beyond what annotations provide.

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

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

Two compact sentences with no wasted words. The main purpose is front-loaded, followed by usage guidance and pairing information. Every sentence adds value.

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

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

For a simple tool with one optional parameter, no output schema, and rich annotations, the description fully covers all necessary information: purpose, usage, behavior, and scoping. The agent can correctly select and invoke this tool without ambiguity.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description adds meaning by explaining that omitting the key lists all saved keys, and provides concrete usage examples (e.g., 'user_research_topic'), which helps an agent understand typical parameter values.

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

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

The description clearly states the action ('Retrieve a value' or 'list all saved keys') and the resource ('values saved via remember'). It distinguishes itself from sibling tools by specifying its role as the retrieval counterpart to '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?

The description provides clear usage context: to look up previously stored context without re-deriving it. It mentions scoping (anonymous IP, BYO key hash, account ID) and pairs with remember/forget. However, it does not explicitly state when to avoid using this tool or provide alternatives among the extensive sibling list, but the intent is well-understood.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by explaining the mark_read parameter's effect on future calls and confirming polling behavior, without contradicting annotations.

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

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

The description is a concise paragraph with four key sentences, front-loading the main purpose and then providing necessary detail. Every sentence adds value with no redundancy.

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

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

With no output schema, the description explains the return fields (source, citation_uri, payload). It covers mark_read behavior and mentions polling, though it omits explicit defaults (e.g., limit=50) and unread_only effect, 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%, so baseline is 3. The description adds practical examples (e.g., 'sec_8k' for type) and clarifies the mark_read semantics, going beyond the schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on retrieving events rather than managing 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?

The description guides usage by mentioning filter options (type, since) and the mark_read feature. It also notes that polls work fine and provides an alternative endpoint for scripts/dashboards, though it lacks explicit 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?

Beyond annotations (readOnly, idempotent, openWorld), description discloses multi-source fanout, GDELT→GNews fallback, USPTO soft-fail, and return format. 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?

Description is front-loaded with example queries, then logically organized by data sources, parameters, and return format. Every sentence adds value without redundancy.

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

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

Given 3 required parameters and no output schema, description fully covers tool behavior, parameter details, return structure, and alternative tool. Complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds significant value: explains `since` formats (ISO date and relative shorthand with examples), suggests typical value, and clarifies `value` accepts ticker or CIK. Goes well beyond schema.

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

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

Description clearly states the tool provides a change feed for a company over a window, with example queries and data sources. It distinguishes from sibling tool entity_profile, making purpose unambiguous.

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

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

Explicitly specifies when to use this tool (for dynamic updates) versus entity_profile (for static profile). Provides context on parallel calls and typical monitoring values.

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

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

Annotations declare idempotentHint=true, not read-only. Description adds scoping by identifier, persistence differences (authenticated vs anonymous). Could mention overwrite behavior but idempotent hint covers it.

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

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

Very concise, front-loaded with purpose. Every sentence earns its place: usage, examples, scoping, retention, pairing. 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?

Covers purpose, usage, behavior, and parameters adequately. No output schema but return value is trivial (success indicator). Missing explicit mention of return type, but not critical for agent use.

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

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

Schema covers both parameters with descriptions. Description adds key examples ('subject_property') and value scope ('findings, addresses'), plus scoping context. Adds value beyond schema.

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

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

Clearly states it saves data for reuse, with specific verb 'save' and resource 'data'. Distinguishes from siblings 'recall' and 'forget' by mentioning pairing.

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 discovering something worth carrying forward. Provides concrete examples (ticker, address, preference) and says to pair with recall/forget.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it notes that each call cascades through several internal lookup endpoints, replacing 2-3 manual lookups. It also details the exact return content for each entity type (ticker+CIK+company_name+citation URI for company; RxCUI+ingredient+brand+citation for drug). No contradiction with annotations.

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

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

The description is fairly long but every sentence adds value. It starts with concrete examples, then gives usage guidance, then details specifics for each type. Could be slightly more concise but is well-organized and front-loaded with key information.

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

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

Given no output schema, the description adequately explains return values for both entity types. It covers the two supported types thoroughly. It could mention error behavior (e.g., if entity not found), but overall it is complete for the tool's purpose.

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

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

Schema coverage is 100% and description adds meaning beyond the schema: for the 'type' parameter, it explains what each option returns; for 'value', it provides examples for different input formats (ticker, CIK, name for company; brand/generic name for drug). This helps the agent understand valid inputs 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 states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It uses specific verb+resource construction ('resolve a user-spoken NAME to the canonical/official identifier') and provides concrete examples of queries it handles ('What's the ticker for...', 'find the CIK for...'). It distinguishes itself by stating it should be used first when needing an ID.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the two supported types and what they return. While it does not explicitly mention when not to use it (e.g., if you already have an ID, use other tools), the context is clear enough for the agent to infer. The sibling tools (entity_profile, compare_entities) have different purposes, so no direct alternative is needed.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds value by disclosing that the tool probes each entity using ai_visibility_check and returns a ranked list with score, confidence, and signal density per entity, which are behavioral traits 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 three sentences, front-loaded with the core purpose, and every sentence adds value without redundancy. It is appropriately concise for the tool's complexity.

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

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

Given the tool has 4 parameters (1 required) and no output schema, the description compensates by detailing the return fields (score, confidence, signal density per entity). It also explains the use case and process, making the description complete enough for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description briefly mentions 'your brand + N competitors' in relation to the entities parameter but does not add significant meaning beyond what the schema already provides for each parameter.

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

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

The description clearly states the tool's purpose: compare AI visibility across multiple entities side-by-side using ai_visibility_check, and it includes details about ranking and output fields, distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides context for when to use the tool (competitive AI-marketing audits) and gives an example question, but does not explicitly state when not to use it or mention alternative tools by name. The context implies it is for comparing multiple entities, which sufficiently guides usage.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds key behavioral details: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed lists timeouts. 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 well-structured with a front-loaded purpose sentence, followed by output details and limitations. It is slightly verbose but every sentence adds value. Could be tighter but still effective.

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

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

Given no output schema, the description thoroughly explains return fields (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem limitations and graceful degradation, making it complete for safe 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 description coverage is 100%. The description confirms scoped packages and default version behavior, but these are already present in the schema. Baseline 3 is appropriate as description adds no new parameter semantics beyond schema.

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

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

The description clearly states it is a composite check for adding an npm package, covering deps.dev and bundlephobia. It specifies what it evaluates (license, advisories, version history, bundle size, etc.) and distinguishes from siblings by noting ecosystem limitations and fallback to deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when-not-to-use: for non-npm, use deps.dev:version directly. This gives clear usage context and alternatives.

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

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

Beyond annotations (read-only, idempotent), it reveals embedding model (BGE-base-en), window size (500-char overlapping), max input length (200K chars with truncation flag), and output details (passages with offsets and scores). No contradiction with annotations.

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

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

Well-structured: opens with purpose, then usage guidance, pairing, and technical details. Every sentence adds value without redundancy.

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

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

No output schema, but description explains return format (top-N passages with character offsets and similarity scores), covers limitations (truncation flag), and provides enough context for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for query and clarifies text as 'document text to search inside', but does not substantially extend schema 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 does semantic search inside a provided text, returning passages with offsets and scores. It differentiates from siblings like ask_pipeworx_grounded by focusing on searching within a fetched record.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. It implies when not to use and provides alternatives.

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

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

The disclosure covers creation, return value, persistence requirement, type-specific parameters, delivery details, SMS caps, and webhook signing beyond annotations, but contradicts the idempotentHint annotation by implying each call creates a new subscription.

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

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

The description is well-structured with front-loaded purpose and outcome, though it could be slightly more concise; still, every sentence provides value.

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

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

Despite lacking an output schema, the description fully explains the return value and covers all essential aspects: prerequisites, types, parameters, delivery options, and constraints, making the tool effectively self-contained.

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

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

The description adds substantial meaning beyond the input schema by providing detailed examples and constraints for the 'type', 'params', and 'delivery' parameters, fully compensating for schema coverage at 100%.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

It specifies prerequisites (Pipeworx OAuth account), enumerates supported types with usage examples, and describes delivery channels, but does not explicitly state when to avoid using this tool.

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

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

Annotations already document readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds that results are drawn from a live catalog of thousands of tools and explains the behavior with and without the 'topic' parameter. It does not contradict annotations. Minor gap: behavior with invalid topic values is not mentioned.

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

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

The description is somewhat long but well-structured: it front-loads common queries, then explains output and usage. Every sentence adds value, covering purpose, output format, and usage instructions.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description covers purpose, when to use, what it returns, how to use the parameter, and how it relates to other meta-tools. It is sufficiently complete.

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

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

Schema coverage is 100%, with the parameter description already listing possible topic values. The description adds examples but does not provide new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point, lists many trigger phrases such as 'what can you do?' and 'getting started', and explains it returns category-bucketed example questions. It differentiates from siblings by positioning this as the first tool to use when unfamiliar with 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?

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance. It does not explicitly say when not to use alternatives, but the context implies it is the starting point.

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 (idempotent, non-destructive), the description adds that the row is deactivated (not deleted) and historical events remain via recent_alerts. 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 two succinct sentences, front-loaded with the core action, and every sentence adds value without redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, ownership, idempotency, and impact on historical data, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% for the single parameter 'id', and the schema already describes it as a UUID from subscribe. The description adds no further parameter detail, so baseline 3 is appropriate.

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

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

The description explicitly states 'Cancel a subscription by id,' providing a specific verb and resource. It also explains the deactivation behavior, 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?

It clearly states that ownership is enforced ('you can only cancel your own subscriptions'), guiding the agent on when to use. However, it does not explicitly mention when not to use or provide 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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds valuable behavioral details: uses SEC EDGAR + XBRL, returns a verdict with extracted structured form, actual value with citation, and percent delta. Also notes 'v1 supports company-financial claims', setting expectations. No contradictions.

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

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

The description is moderately long but well-structured: starts with intuitive examples, states usage, then details supported claims and output. Every sentence adds value, though some could be tighter. No unnecessary 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 a single parameter and no output schema, the description covers the tool's operation, data sources, output format (verdict, extracted form, actual value, citation, delta), and limitations (v1, company-financial). It is sufficiently complete for an agent to understand when and how to invoke the tool.

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

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

Only one parameter with 100% schema coverage. The description adds natural-language examples of claims (e.g., 'Apple's FY2024 revenue was $400 billion'), which enhances understanding beyond the schema's description. The examples illustrate the expected input format.

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

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

The description clearly states it performs natural-language claim verification against authoritative sources, with specific examples like 'Is it true that…' and 'fact check'. It distinguishes from siblings by noting it replaces 4–6 sequential calls, showing a clear 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It does not explicitly state when not to use or list alternative tools, but the context of sibling tools provides implicit differentiation.

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