Mydisease

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: probing multiple models, scoring, returning per-model details, and that Anthropic calls require a BYO key with direct payment to Anthropic. 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 a single, well-structured paragraph of about three sentences. It front-loads the core action and scoring, then provides details on models and output. Every sentence adds value with 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 there is no output schema, the description explains the return format (per-model: score, confidence, signals, raw_response + combined view). It covers all parameters, usage context, and output, making the tool fully understandable.

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 parameters have schema descriptions, but the description adds meaning: default model is Workers AI Llama-3.3-70b (free), and entity can be a brand, product, person, or topic. This goes beyond the schema's generic 'The thing to ask about'.

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

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

The description clearly states the tool's purpose: probing LLMs for AI visibility of a business/brand/product/topic and scoring it 0-100 per model. It specifies the default model and optional API key, and distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on visibility scoring.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the API key for Anthropic. However, it does not explicitly mention when not to use this tool or compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it routes to 5,529 tools, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a one-call default. This enriches understanding beyond the structured hints.

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

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

The description is long but efficiently front-loads the most critical instruction ('PREFER OVER WEB SEARCH') and then systematically covers domains, examples, and alternative tools. Every section serves a purpose, though a few sentences could be 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?

For a tool of this complexity (5,529 sources, no output schema), the description is exceptionally complete: it explains the routing behavior, the citation URI return format, alternatives, breadth of coverage, and even addresses breaking news handling. No significant gaps remain.

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

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

Schema coverage is 100%—all six parameters are clearly documented as aliases for the natural-language question, with examples. The description itself adds no new parameter-specific meaning, but it does reinforce that the tool fills arguments automatically, which is mildly informative. 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 this is a broad factual question-answering tool that routes to thousands of verified sources. It distinguishes itself from sibling tools by specifying when to prefer it over ask_pipeworx_grounded and deep_research, and explicitly positions it as the default entry point.

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

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

It provides explicit when-to-use guidance with detailed examples ('current US unemployment rate', 'Apple's latest 10-K') and directly names alternatives for when NOT to use it: 'for a hallucination-resistant single answer ... use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research'. This goes beyond merely implying context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond that: it is a beta with 'candidate routing improvements enabled live', the candidate was retired on a specific date, and results are compared for merge decisions. This discloses temporal variability and experimentation without contradicting 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 and front-loaded with the key identity ('Beta version of ask_pipeworx'). Each sentence provides distinct information: identity and scope, current experimental state, and usage guidance. It is slightly dense but not verbose, earning a strong score without being perfectly concise.

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

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

The tool has no output schema, but the description compensates by specifying 'same response shape' as ask_pipeworx, which gives the agent enough to know what to expect. It covers the beta nature, current state, and usage context. With strong annotations and a clear relationship to its sibling, the description is complete for practical invocation, though it does not detail edge-case behaviors like failure modes or latency.

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 all parameters with 100% coverage, describing 'question' and its five aliases (q, text, input, query, prompt). The description only reiterates 'same arguments' without adding new parameter-level detail, so it relies on the schema. Per the baseline, a score of 3 is appropriate when schema coverage is high and description adds no extra semantic value.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx' that acts as an 'identical universal router' with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by emphasizing candidate routing improvements and its experimental nature, making the purpose precise and non-confusable.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies current behavior ('No candidate is active right now... this currently matches ask_pipeworx exactly') and states it is a full working router, giving clear when-to-use guidance and implicitly naming the stable alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: it costs one extra LLM call, returns structured refusal reasons, and provides verbatim evidence. This goes well beyond the annotations and clarifies operational nuances.

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 every sentence earns its place: purpose, behavior, return format, usage, and cost trade-off are packed into three well-structured sentences. Information is front-loaded with the core value proposition ('Hallucination-resistant answer mode'), and there is zero wasted wording.

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?

Without an output schema, the description fully explains the success return object ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and failure refusal reasons. It also covers the key cost trade-off and use cases, making the tool's behavior completely understandable for an agent.

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

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

The input schema already covers all parameters and aliases with 100% description coverage, so the schema carries the full burden for parameter meaning. The description does not add any parameter-specific semantics, so 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's purpose and context. It also distinguishes this tool from its sibling ask_pipeworx by explaining that it extracts answers only from tool results, making its unique role unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also tells the agent when not to use it with 'prefer ask_pipeworx for casual lookups,' giving clear alternatives and exclusions.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds extensive behavioral detail: low-confidence short-circuiting, closed market handling, wide-spread warnings, cancellation rule parsing, and fan-out logic. 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?

While front-loaded with the core purpose, the description is very lengthy and includes many details (classifiers, fan-out examples, response shapes) that could be streamlined. It uses section-like formatting, but conciseness is sacrificed for completeness.

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

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

Given the tool's complexity (multiple outcomes, conditional behavior, no output schema), the description thoroughly covers edge cases, warning flags, and return value structure. Nothing critical is omitted.

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

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

Schema coverage is 100% with descriptions, but the tool description further enriches each parameter: explains input formats for 'market', quick vs thorough for 'depth', and file-size implications for 'include_raw'. This adds significant 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 uses a specific verb-resource pairing ('Research a Polymarket bet'), clearly defines inputs (slug, URL, question text), and distinguishes from sibling tools by focusing on data retrieval and evidence packet generation.

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

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

Explicit usage scenarios are given ('Use for...'), and examples for different bet categories are provided. However, it does not explicitly state when NOT to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral details: correct handling of off-calendar fiscal years, sorted results by primary metric, data sources per type, and return of citation URIs. No contradiction.

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

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

The description is a single dense paragraph that front-loads the purpose with example queries. It covers all essential aspects efficiently, though slightly more structured formatting (e.g., bullet points) could improve readability.

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

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

Given the 2 parameters and no output schema, the description is quite complete: it explains the different data for company vs drug types, sorting, and citation URIs. It does not detail output format but that is acceptable for a comparison tool with simple returns.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds valuable context beyond schema: explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and the sorting behavior, enhancing understanding of how parameters affect results.

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 that the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, and provides example queries ('X vs Y', 'which is bigger'). It distinguishes from sibling tools by advising to 'ALWAYS PREFER over sequential single-pack lookups when comparing 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 gives clear guidance on when to use: for comparing entities, with specific query patterns. It also informs about the entity types and data sources. However, it does not explicitly state when not to use (e.g., for single entity details), but the sibling context implies 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 the readOnly/openWorld/idempotent hints, the description discloses account and plan requirements, latency ranges, gap[] behavior, contradiction handling, citation_uri fetchability, semantic excerpting, and hop semantics. No contradiction with the annotations is present.

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 and front-loaded, and every sentence carries information without filler. However, it is a long single block that could be even more scannable with structured sections or bullet points.

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

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

Given the tool's complexity and the lack of an output schema, the description fully compensates by covering prerequisites, use cases, alternatives, depth variants, output fields, gaps, contradictions, citations, timeout, and limitations. It is remarkably 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?

While the schema already covers both parameters, the description adds meaningful depth-level semantics (quick/standard/thorough with specific hop and gap-recovery behavior) and clarifies that 'question' can be broad or multi-part in natural language. This goes beyond the schema's surface-level 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition, parallel routing, and a findings packet. It also distinguishes itself from open-web search and from sibling tools like ask_pipeworx.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and current-news topics should prefer ask_pipeworx. It also gives a concrete fallback if the agent is not signed in.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context about return format (top-N with full schemas, ready to call) and curated examples, going beyond annotation information.

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

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

Two sentences: first states purpose and scope, second describes return value and usage guidance. No extraneous content. Highly 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?

With 6 params, no output schema, description covers return structure sufficiently. Lacks details on sorting/relevance but minor given the discovery nature. Adequate for agent invocation.

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

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

Schema coverage is 100% with descriptions. Description adds value by grouping aliases (task, q, search, description) and explaining the natural language input style. Provides example queries, enhancing 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 finds tools by describing data/task. Lists many domains and explicitly differentiates from siblings like deep_research and query by advising 'Call this FIRST' when exploring options.

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

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

Explicitly says when to use: for browsing/discovering tools across many domains, and when not to: when you already know the tool or want a specific answer. Directly addresses alternatives.

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

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

Adds significant context beyond annotations: details cross-referenced data sources (MONDO, DisGeNET, HPO, CTD). No contradiction with readOnlyHint or idempotentHint.

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

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

Three sentences, front-loaded with purpose, then id details, then return data, then usage tip. No wasted words.

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

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

For a complex multi-source fetch tool, description covers input, return contents, and usage flow. No output schema but return described adequately.

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

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

Schema coverage 100% (baseline 3). Description adds meaning: explains id prefix examples and fields as comma-separated with default. 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?

Clearly states 'Fetch the full aggregated annotation object for a single disease id.' with specific verb and resource. Distinguishes from sibling 'query' by noting that tool resolves name to 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?

Explicitly says when to use (have a disease id) and recommends prerequisite step (use 'query' to resolve name). No explicit when-not, but clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it explains the parallel call, sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), return fields with formatting (e.g., pipeworx:// URIs), a known soft-failure (patents sunset), and fallback strategy (GDELT→GNews). No contradictions with annotations.

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

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

The description is lengthy but well-structured: examples first, then high-level purpose, then detailed output. Every sentence adds value, though there is minor redundancy (e.g., 'US public company' mentioned twice). Overall concise for the amount of 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 the tool's complexity (multiple sources, fallbacks, limitations), the description covers identification, output fields, constraints (names not supported, patent sunset), and usage priority. Lacks exact response structure but provides enough detail for an agent to invoke correctly. Open-world hint is already in annotations.

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

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

Schema covers both parameters with descriptions (100% coverage). The description reinforces param usage with examples and adds context: explains why names are unsupported and suggests resolve_entity. This extra guidance justifies a score above baseline 3.

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

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

The description clearly states the tool retrieves a full cross-source profile of a US public company in one call, with examples ('Tell me about X', 'research Acme'). It distinguishes from siblings like resolve_entity and compare_entities by specifying its holistic scope and parallel execution.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and 'use resolve_entity first if you only have a name.' This tells the agent when to use this tool and when to use an alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, but the description adds context about clearing sensitive data and confirms deletion behavior. It does not elaborate on error handling or edge cases, but the annotations handle the core safety profile, so a 4 is appropriate.

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 with no wasted words: three sentences covering purpose, usage, and sibling pairing. It is front-loaded with the action and resource.

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

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

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, when to use, and relationships to siblings. No gaps are evident.

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 merely mentions 'by key', adding no new meaning beyond the schema. Baseline 3 is correct.

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 'Delete a previously stored memory by key,' using the verb 'delete' and resource 'memory' with a specific method 'by key'. It explicitly pairs with siblings 'remember' and 'recall', distinguishing its role clearly.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also instructs to pair with siblings, giving clear guidance on when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the process: fetches the page, extracts title/description/key links, and emits standard markdown format. It also notes the output is a single text blob ready for site-root placement.

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

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

The description is two sentences: one for purpose and process, one for use cases. It is front-loaded with the primary purpose and contains no extraneous words.

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

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

For a tool with 2 parameters (1 required), no output schema, and rich annotations, the description covers purpose, process, and use cases. It does not explain error handling or detailed output structure, but the output is described as a 'single text blob' which is sufficient for this simple tool.

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

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

Schema description coverage is 100% with clear descriptions for both parameters (url and max_links). The tool description reiterates the default and max for max_links but adds no new meaning beyond the schema.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file for any URL'). It clearly distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating a standard file format for AI crawler indexing.

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 lists three explicit use cases: getting a client's site indexed, drafting for own project, or auditing a competitor's site. It provides context but does not explicitly state when not to use it or compare directly to sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field details and optional parameter behavior, which is valuable given no output schema.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and well-structured.

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

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

Simple tool with one optional parameter and no output schema. Description covers purpose, return fields, and usage guidance adequately.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema's definition of include_inactive. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicit guidance on when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds specific behavioral context by detailing the returned data (count, sources, versions), which goes beyond annotations.

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

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

The description is a single, front-loaded sentence that conveys all necessary information without any waste.

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

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

The description covers the key output elements (count, sources, versions) but could be slightly enhanced by specifying the output format or structure. However, it is sufficient for an agent to understand what to expect.

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

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

The input schema has no parameters, so the baseline is 4. The description does not need to add parameter meaning; it correctly focuses on the output.

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 build metadata including total disease count, annotation sources, and versions. It is specific and distinct from sibling tools like 'disease' or 'query'.

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 tool has no parameters and is self-explanatory as a metadata retriever. While it does not explicitly mention when not to use or alternatives, its purpose is clear enough for an agent to decide when to invoke it.

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

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

With no annotation hints (all false), the description carries the full burden and does so thoroughly. It discloses the claim_token return mechanism, rate limiting (5 per identifier per day), cost ('Free; doesn't count against your tool-call quota'), and the team's daily review process, giving the agent a complete picture of side effects and follow-up behavior.

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

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

The description is long (9 sentences), but every sentence earns its place, covering purpose, usage, exclusions, message guidance, follow-up, rate limits, and cost. It is front-loaded with the core purpose and well-structured, though slightly verbose for a feedback tool.

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

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

Given 4 parameters, a nested object, no output schema, and no annotation hints, the description covers everything needed: purpose, when to use, what to include, exclusions, follow-up workflow, rate limits, and impact. It even clarifies the return value (claim_token) without an output schema, making it fully self-contained.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds extra value by guiding message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explaining the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'). This goes beyond the schema but is partially redundant with the schema's parameter 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 first sentence, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' uses a specific verb and resource, clearly distinguishing it from siblings like ask_pipeworx. It further enumerates concrete use cases (bug, feature, data_gap, praise), making the purpose unmistakable.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and provides a clear exclusion with an alternative ('if the tool came from a different MCP server... file it with that server instead'). It also gives guidance on what not to do ('don't paste the end-user's prompt'), making usage context exceptionally clear.

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

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

Annotations already declare readOnly and idempotent. The description adds behavioral detail: data source (CF analytics-engine), caching (5min-1h), and privacy (no PII). No contradictions.

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

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

The description is concise (5 sentences) with a clear structure: result summary, use cases, data derivation note. No wasted words.

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

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

For a low-complexity tool with one optional parameter and no output schema, the description covers return content, use cases, data source, caching, and privacy completely.

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

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

The schema covers the single parameter with enum and description. The tool description expands on the parameter by explaining the effect of different window durations (short-term vs. steady-state demand), providing meaning beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over selectable windows. It differentiates from siblings like 'discover_tools' by focusing on real-time agent usage trends.

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

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

Explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). Window selection guidance is given. No explicit when-not-to-use, but context is sufficient.

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

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

Annotations (readOnlyHint, idempotentHint) are complemented by detailed behavioral context: scanning logic, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against CLOB depth, and referral to polymarket_fill_risk. 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 thorough but slightly verbose. It is well-structured with clear sections for each mode and details, but some sentences could be condensed 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?

Despite no output schema, the description explains the response structure (opportunities[], partition_check, fill check) and covers edge cases (placeholder filters, similarity threshold). It is 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 description coverage is 100% and the description adds significant context: event parameter accepts slugs or URLs, topic parameter enables cross-event scanning, and the no-arg case is explained. This goes well 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between no-arg trending scan, event mode, and topic mode, making the purpose specific and differentiable from sibling tools.

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

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

Explicit guidance on when to use each argument: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Also provides when-not-to-trade conditions (realizable_edge_pp ≤ 0).

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral details: caching 1h at KV level, response structure with by_segment, fed_candidates, _diagnostics, and edge calculation specifics. 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 overly long and dense with technical details, making it less concise. While comprehensive, it could benefit from better structuring (e.g., bullet points) to improve readability for an AI agent.

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), the description is highly complete, covering edge calculation, model families, response structure, diagnostics, tradeable-edge knobs, caching, and exclusions (Fed bets). It ensures the agent can operate 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?

All 9 parameters have schema descriptions (100% coverage). The description adds extra context for several parameters, e.g., slippage_pp explains Polymarket fees and when to adjust, min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, designed for discovering betting opportunities. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker through its unique approach of model families and edge calculation.

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 when to use ('what should I bet on today') and provides guidance on tradeable-edge knobs. However, it lacks explicit comparison to sibling tools, though it mentions Fed bets are excluded, implying when not to use for Fed markets.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: it reads snapshots, computes trend and decay metrics, and notes limitations like 60-day TTL and snapshot gaps. No contradictions with annotations.

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

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

The description is somewhat lengthy but well-organized, starting with the core purpose and using labeled sections (RESPONSE, LIMITS). Most sentences add value, though a few could be streamlined without losing clarity.

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

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

Given no output schema and only two parameters, the description covers all essential aspects: purpose, usage context, response structure (including edge cases like expired opportunities and snapshot gaps), and limitations. It is remarkably complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds contextual meaning: it specifies default values, clamps for 'days', and defines 'window' as a snapshot family. These details aid proper usage beyond the schema's bare descriptions.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge data.

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

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

The description provides context on when to use the tool, illustrating the significance of edge age with a concrete example. It does not explicitly list when not to use it or alternative tools, but the domain-specific framing makes usage boundaries clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavioral context: walking the ladder, returning verdict (clean/degraded/cannot_fill), and crucially disclosing that partial basket fills convert an arb into an unhedged directional position (the dominant loss mode). 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 structured clearly with bold headings and separate sections for single-market and basket modes, front-loading the core purpose. It is slightly verbose but every sentence adds value; minor redundancy could be tightened but overall 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?

Despite lacking an output schema, the description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers risk of partial fills and size limits, making the tool 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?

Schema description coverage is 100%, and the description adds significant meaning: for 'side' it explains auto behavior in basket mode, for 'size_usd' it clarifies interpretation per mode (max spend on buys, target proceeds on sells, settlement notional for basket). Defaults and clamps are also provided.

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

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

The description explicitly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing between single-market and basket modes. It lists specific outputs (e.g., top_of_book, vwap_fill_price) and directly references sibling tools polymarket_arbitrage and polymarket_edges, making differentiation 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 explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it (theoretical overround not capturable, partial fills causing directional risk) and covers mode-specific parameter usage and defaults.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: compatibility_warning conditions, temporal alignment, skipped leg-pair comparisons, and real-world rarity. 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 relatively long but well-structured: purpose, modes, response format, safety fields. Each sentence adds value. Could be slightly tighter but is efficient given the complexity.

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

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

No output schema, but the description details the response structure (leg-by-leg prices, matched spread, top_spreads_pp, safety fields) and explains edge cases. Covers most necessary 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?

Input schema has 100% coverage with each parameter described. The description adds value by explaining the two usage modes and giving concrete examples for each mode, as well as the mutually exclusive nature of topic vs explicit parameters.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by focusing on cross-venue comparison, while siblings like polymarket_arbitrage or polymarket_edges are Polymarket-only.

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

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

Explicitly describes two modes (topic and explicit) and when to use each. Warns that most pre-mapped topics return compatibility_warning, and 'pre-mapped ≠ tradeable'. Also explains safety fields that indicate when spreads are invalid, providing clear 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 readonly, open-world, idempotent, and non-destructive hints. The description adds context such as hits keyed by MONDO IDs and best-matching keys, and clarifies behavior for free-text vs fielded queries, which is valuable beyond annotations.

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

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

Two concise sentences: first defines purpose, second gives usage guidance and examples. No redundant or irrelevant information. Every sentence earns its place.

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

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

Given the simple schema and annotations, the description fully covers the use case, parameter behavior, and relationship to siblings. It explains what the tool returns (hits keyed by MONDO ID) despite no output schema, which is sufficient for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. Description provides examples ('diabetes', 'mondo.label:asthma') and clarifies fielded query syntax, adding meaning beyond the schema's property descriptions.

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

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

Description clearly states the tool searches MyDisease.info for diseases by free-text or fielded query, returning matches keyed by MONDO IDs. It distinguishes itself from the sibling 'disease' tool, saying to use this tool to resolve 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?

Explicitly advises to use this tool to resolve disease names to canonical ontology IDs before calling the 'disease' tool. It provides examples for free-text and fielded queries, though it does not explicitly state when not to use it.

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

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

The description adds behavioral context beyond annotations, including scoping to identifier (anonymous IP, BYO key hash, account ID) and dual behavior (list vs. retrieve). It aligns with readOnlyHint, idempotentHint, and destructiveHint 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 concise (two sentences) yet comprehensive, front-loading the core action and proceeding to examples, scoping, and related tools. Every sentence adds value with no redundancy.

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

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

Given the low complexity (one optional parameter, no output schema), the description fully covers purpose, usage, parameters, scoping, and relationships to siblings. No gaps remain for effective 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?

The single parameter 'key' is fully covered by schema (100% coverage). The description adds critical meaning: omitting the key lists all saved keys, providing behavior beyond schema alone. Examples further clarify usage.

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

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

The description clearly states the tool's purpose: retrieve a saved value by key or list all keys when omitted. It distinguishes itself from siblings 'remember' and 'forget' by specifying the operation and pairing guidance.

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 guidance with concrete examples (target ticker, address, research notes) and explains when to use it (look up stored context) and when not to (e.g., use forget for deletion). It also mentions scoping and pairing with siblings.

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

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

The description discloses that mark_read affects subsequent calls, mentions return fields, and references the same feed via HTTP. No contradiction with annotations (readOnlyHint, idempotentHint, etc.). Adds value beyond annotations by explaining mark_read behavior and data content.

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

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

Three sentences with clear structure: purpose, return details, filtering and mark_read explanation, and alternative endpoint. No fluff, front-loaded with key 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?

For a tool with 5 params and no output schema, the description covers primary functionality, filtering, return fields, and an alternative use case. Lacks explicit mention of default limit or pagination, but schema covers limit default.

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

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

Schema coverage is 100%, but description adds meaning by giving an example for type ('sec_8k'), clarifying since as ISO timestamp, and explaining mark_read's effect on next call. This enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies returned fields (source, citation_uri, raw payload), and mentions filtering. It is distinct from sibling tools like 'subscribe' or 'list_subscriptions' with its focus on recent alerts.

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

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

The description provides usage context: polling is fine, filtering options (type, since), and an alternative HTTP endpoint for scripts/dashboards. It lacks explicit contrast with sibling tools but offers clear guidance on 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 true. The description adds significant context about fan-out to multiple sources, fallback logic, soft-failure for USPTO, and return structure including pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is well-structured with example queries, enumerated sources, and clear parameter explanations. It is slightly long but each sentence adds value. Front-loaded with usage examples.

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 (aggregating multiple sources, fallback, soft-failure), the description provides comprehensive guidance. It describes return structure (changes[], total_changes, citation URIs), fallback logic, and when to use an alternative tool. No output schema exists but the return format is sufficiently described.

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 3 parameters. The description adds value by explaining 'since' accepts ISO dates or relative shorthand (e.g., '30d', '1m'), 'value' can be ticker or CIK, and 'type' is restricted to 'company'. It also gives typical usage recommendation for 'since'.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' by aggregating from multiple sources. It gives specific verb 'returns structured changes[] grouped by source' and distinguishes from the sibling 'entity_profile' which is for static profiles.

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 this tool, e.g., for queries like 'What's new with X', and when not to: 'Use entity_profile instead when you want the static profile'. It also explains fallback behavior between GDELT and GNews, and soft-failure for USPTO.

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

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

Description adds behavior beyond annotations: scoping by identifier, persistence duration for authenticated vs anonymous sessions. Annotations only idempotentHint true; description gives essential storage details.

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

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

Three sentences, front-loaded with purpose, then usage, then behavior. Every sentence is necessary and concise. No redundant 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, storage scoping, persistence, and sibling tools. No output schema, but return value not critical for this tool. Could mention overwrite behavior, but not essential.

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

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

Schema coverage 100% with clear descriptions. Description provides examples but adds no new semantic meaning beyond what's in 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?

Description uses specific verb 'Save' and resource 'data to reuse later', clearly distinguishing from siblings 'recall' and 'forget' by naming them as partners. Examples like 'resolved ticker, target address' make purpose concrete.

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

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

Provides explicit use cases ('when you discover something worth carrying forward') and examples. Mentions pairing with recall and forget. Lacks explicit when-not-to-use guidance, 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it explains that LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable, that identifiers are labelled with their source, and that unresolved identifiers are explicitly reported under 'unresolved' rather than omitted. It does not contradict the annotations.

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

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

The description is longer than average but every sentence carries information: usage examples, scope, supported types, input acceptance, degradation behavior, and internal cascading. It is front-loaded with examples and core purpose. It earns a 4 because of the density and structured flow, though it could be slightly more scannable.

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

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

Given the complexity (two entity types, multiple identifiers, enrichment dependencies) and that there is no output schema, the description is remarkably complete. It explains what results are returned (identifiers with source labels, unresolved list), how to invoke it (input types), and failure behavior (graceful degradation). It also covers return behavior for the 'drug' type, including RxCUI and citation. This satisfies the contextual burden for a moderately 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?

The input schema has 100% coverage with descriptions for both required parameters, including examples (e.g., 'ticker (AAPL), CIK (0000320193), or name' and 'brand or generic name'). The description itself reinforces accepted formats and adds semantic nuance (e.g., 'cross-source identity spine'), so it 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 immediately provides example user queries ('What's the ticker for…') and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This is a specific verb+resource pairing that distinguishes it from siblings like entity_profile or compare_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 explicitly says 'Use FIRST whenever you have a name but need an ID.' It also notes that 'using resolve_entity replaces 2-3 manual lookups,' giving clear context on when to prefer this tool over alternatives. This is direct usage guidance with a rule of thumb.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so no need to repeat. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, providing useful behavioral context beyond annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core functionality and immediately provides a concrete use case example. Each sentence earns its place.

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

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

Given full schema descriptions, clear annotations, and no output schema, the description adequately explains the tool's purpose, inputs, and expected output (ranked list with metrics). It leaves out only minor details like how scores are computed, but is complete enough for effective 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 description coverage is 100%, so baseline is 3. The description adds meaning by explaining that entities should include the subject first and that context can disambiguate common names, which goes beyond the schema's plain descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, identifying the most and least recognized. It uses specific verbs and resources, and distinguishes from sibling tools like ai_visibility_check (single entity) and entity_profile.

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 indicates the tool is for competitive AI-marketing audits and that the first entity is the subject, with competitors following. It implicitly suggests using ai_visibility_check for single entities, but does not explicitly list when not to use this tool or mention alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: it fans out across external services, mentions specific partial failure scenarios (bundlephobia timeout, sources_failed), and lists the return fields. 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 moderately long but well-structured: starts with the composite nature, then usage guidance, output summary, and limitations. Every sentence adds value, and it is front-loaded with the key purpose. Slightly verbose in the middle but still concise overall.

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 fully explains the return values (summary block, per-advisory detail, links, alternative versions) and covers partial failure behavior. For a tool with 2 parameters and high schema coverage, this is very complete.

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

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

Schema coverage is 100% for both parameters (package and version), with clear descriptions in the schema. The description adds minimal extra value beyond what is in the schema (e.g., mentioning scoped packages, which is already in 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 defines the tool's purpose: a composite check for evaluating npm packages using deps.dev and bundlephobia. It specifies the resources checked (license, advisories, version history, bundle size, etc.) and differentiates from sibling tools which are unrelated (e.g., bet_research, scan_competitor_ai_presence).

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

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

The description explicitly states when to use this tool ('is X safe / popular / small', 'what does adding lodash cost me') and provides limitations: NPM ecosystem only in v1, with fallback guidance to deps.dev:version for other ecosystems. It also explains partial failure behavior and graceful degradation.

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

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

Adds rich behavioral details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and passage offsets. No contradiction with annotations.

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

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

Single, efficient paragraph with front-loaded purpose. Every sentence adds value, no fluff.

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

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

Covers all aspects: purpose, usage, behavior, parameters, and return format (passages with offsets and scores) despite no output schema.

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

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

Schema coverage is 100%, but description adds default value and range for 'limit' (1-20, default 5) and provides query examples, adding 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?

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes itself from alternatives like ask_pipeworx_grounded and implies use when record is too large.

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 when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Does not explicitly list when not to use, but context is clear.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds important behavioral context: OAuth requirement, type-specific filter examples, delivery constraints (SMS cap, webhook signing and auto-disable), and always-on feed. However, it does not explicitly clarify idempotency behavior given the idempotentHint=true annotation; the description says 'create' and 'new subscription id' which could imply non-idempotent, but not necessarily contradictory.

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

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

The description is front-loaded with the main purpose and requirements, then systematically covers types and delivery. It is informative but slightly verbose; could be trimmed slightly while retaining all essential details. Still well-structured.

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

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

Given the complexity of the tool (multiple subscription types, delivery channels, and constraints) and no output schema, the description is remarkably complete. It covers all configuration aspects, prerequisites, and behavioral details like auto-disable and caps.

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

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

The schema has full coverage, and the description significantly enriches each parameter with examples and constraints (e.g., enum types like sec_8k with items codes, polymarket_edge with topics, delivery with webhook signing details). This adds high 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 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value 'Returns the new subscription id.' It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and configuration.

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

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

The description provides explicit guidance: requires Pipeworx OAuth account, details on subscription types and their parameters, delivery channel options with prerequisites (e.g., phone verification, 10/day cap), and webhook auto-disable after failures. This helps the agent decide when to use this tool vs. alternatives.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. Description adds context of being an onboarding tool, and explains return format (category-bucketed example questions with tool calls). 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 relatively long but well-structured: starts with alternative phrasings, then purpose, output description, and usage note. Every sentence adds value.

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

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

Despite no output schema, the description fully explains the return type (category-bucketed example questions with tool+argument shape). For a simple tool with one optional param and strong annotations, it is complete.

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

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

Schema coverage is 100%. Description expands on the optional 'topic' parameter by listing example values (finance, pharma, betting) and explaining behavior with and without 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 this is an onboarding entry point that returns example questions. It uses specific verbs like 'suggest questions' and differentiates from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly advises to use this FIRST when the agent doesn't know what Pipeworx can do. Mentions calling with no arguments for full spread or with topic for focus. Does not explicitly state when not to use, but context is clear.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and linkage to recent_alerts. Annotations already indicate non-readonly and non-destructive, which the description reinforces 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 two sentences, front-loaded with the action, and every sentence adds value. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, deactivation, and reference to recent_alerts. It could mention error handling for invalid IDs, but overall it is sufficient.

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

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

Schema coverage is 100% and the schema already describes the parameter as 'Subscription id (uuid)'. The description does not add new parameter-level details beyond the verb, so it meets the baseline 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?

The description clearly states 'Cancel a subscription by id', a specific verb+resource. It distinguishes from siblings like subscribe and list_subscriptions by indicating ownership enforcement and deactivation behavior.

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

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

The description explains when to use the tool and provides context on ownership enforcement and deactivation, which guides selection against alternatives. It implies that for historical data, recent_alerts should be used, but does not explicitly list when not 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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds crucial behavioral nuance: it explains the verdict set, warns that 'could_not_verify' means the check did not happen and must not be treated as evidence, and clarifies the difference between it and 'unsupported'. 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?

The description is verbose but well-structured, front-loading purpose and usage before diving into return values and caveats. It contains necessary detail for a tool with complex semantics, though a few redundant phrases ('natural-language claim verification' vs 'factually correct') 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?

Since there is no output schema, the description carries the full burden of explaining return values. It lists verdict outcomes, mentions the actual value with citation and reasoning, and thoroughly explains edge cases like 'could_not_verify' and 'unsupported'. It also covers both execution paths, making it complete 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?

The input schema provides 100% coverage for both parameters, including a concrete example for 'claim' and full semantics/tolerance for 'tolerance_pct'. The description adds no additional parameter-level detail beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description explicitly states the tool's function: 'natural-language claim verification against authoritative sources' with trigger phrases like 'fact check' and 'verify the claim that'. It distinguishes this tool from siblings by detailing two processing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for other facts), making its scope unmistakable.

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

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

It provides clear when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies coverage (all factual claims) and internal routing. However, it doesn't explicitly name alternative tools or state when not to use it, which would earn a 5.

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