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 provide readOnlyHint, idempotentHint, and destructiveHint, covering safety and non-mutating behavior. The description adds valuable behavioral context: it routes across 5,798 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and handles live news queries. A small gap is that it doesn't mention failure modes or rate limits, but the annotation coverage lowers the bar and this description clears it.

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

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

The description is long but front-loaded with the most important directive: 'PREFER OVER WEB SEARCH'. It uses structured lists and examples to efficiently convey scope, trigger phrases, and alternatives. While it could be trimmed slightly, every section adds operational value for the 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 of a routing tool with many siblings and no output schema, the description is complete enough: it explains input, intended use, routing behavior, output format (structured answer with citations), and when to use alternatives. It does not detail exact return shapes, but for tool selection and invocation this 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?

The input schema has 100% coverage with descriptions for all aliases and the main 'question' parameter, so the schema already carries the parameter documentation burden. The description adds context about what kinds of questions are appropriate and what the tool does with them, but it does not add syntax or formatting details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: route natural-language factual questions to appropriate verified data sources and return structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can confidently select it without opening its schema.

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 is exemplary in usage guidance. It explicitly says to prefer this over web search for a broad list of data categories, gives trigger phrases like "what is" and "look up", provides concrete examples, and names alternatives with the exact conditions under which to choose them instead.

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 read-only, idempotent, non-destructive annotations, the description discloses that this is an experimental edge with candidate routing improvements enabled live, that no candidate is currently active, and that results are compared against the stable router. It also clarifies that it is a full working router with no fallback, which is valuable behavioral context the annotations do not convey.

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: identity, current experimental status, usage instruction, and reassurance that it is a complete router. The key differentiator — beta vs stable — appears first, and the length is justified by the nuance around live candidate testing.

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

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

For a routing tool with a simple question/alias parameter set, the description is fully sufficient. It names the stable sibling, explains current behavior, confirms the response shape matches ask_pipeworx, and the annotations cover safety and idempotency. Nothing essential is missing.

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

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

The input schema has 100% coverage and already documents the 'question' parameter and all its aliases. The description adds that the tool shares ask_pipeworx's arguments, but it does not need to repeat parameter details since the schema fully handles them. This meets the baseline for schema-backed parameter documentation.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router over 5,798 tools with the same arguments and response shape. It distinguishes this beta variant from the stable ask_pipeworx sibling, so an agent knows exactly what the tool does and how it differs.

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 tells the agent to use this tool when it wants the newest routing and to use it exactly like ask_pipeworx. It also notes when no candidate is active and that it currently matches the stable router. It could be stronger by explicitly stating 'use ask_pipeworx when you want the stable version,' but the guidance is otherwise 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, idempotent, openWorld, and non-destructive behavior. The description adds substantial context beyond those: it only uses the fetched tool result, returns an evidence quote, includes explicit refusal reasons, and costs an extra LLM call relative to the sibling. This is strong disclosure with no contradiction of 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 dense but well-structured: it front-loads the core identity, then details response shape, refusal behavior, usage guidance, and cost trade-off. There is slight redundancy between 'hallucination-resistant' and 'must not invent facts,' but overall 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?

With no output schema, the description fully explains the return shape, including success fields, refusal reasons, and what triggers a refusal. It also gives a cost comparison with the sibling and clear usage boundaries, so an agent has everything needed to invoke it correctly in context.

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

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

Schema description coverage is 100%, with the schema already documenting the required 'question' parameter and all aliases. The description does not add parameter-specific detail, but it does not need to because the schema carries the full burden. 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 states a specific verb and resource: a hallucination-resistant answer mode that extracts answers only from tool results. It explicitly contrasts itself with ask_pipeworx, making it easy for an agent to distinguish between the two siblings.

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

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

The description gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on in high-stakes contexts. It also names the alternative and the condition to prefer it: casual lookups should use ask_pipeworx because this mode costs an extra LLM call.

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?

Annotations declare readOnlyHint=true and idempotentHint=true, so the safety profile is already covered. The description adds substantial behavior beyond annotations: it states that findings never invent data (explicit gaps[]), that every finding carries hop and citation fields, that citations are fetchable via resources/read, that large records are semantically excerpted rather than head-truncated, and that contradictory findings are flagged. It also sets timing expectations (15-60s, up to 90s for thorough). This provides deep, honest behavioral transparency.

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

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

The description is dense but front-loaded with the most operationally critical constraint (account required). Every sentence earns its place by covering a distinct behavioral fact: from the account requirement to the NOT open-web distinction, to depth semantics, to the citation contract, to timing. It is long, but the complexity of the tool justifies the length; a shorter description would lose material routing and expectation-setting information. Slight deduction for a few run-on clauses that could be tightened.

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

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

Given the tool has no output schema, the description fully compensates by explaining what the return packet contains: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers prerequisites (account, paid tier for thorough), latency expectations, and failure modes (gaps for absent topics). An agent could call this tool correctly and interpret its results without needing anything else.

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

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

Schema description coverage is 100%, so the schema already documents both question and depth. The description adds meaningful semantic context beyond the schema by explaining what depths mean in behavioral terms: quick=3 facets, standard=3 with gap recovery and contradiction scan, thorough=6 with iterative lead chasing. It also says breadth is fine for the question field ('Broad/multi-part is fine — decomposition is the point'). This goes beyond the schema enum descriptions.

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

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

The description gives a specific verb and resource: performing grounded multi-source research across Pipeworx's 1517 structured data sources in a single call. It clearly differentiates from siblings by explicitly stating 'this is NOT open-web search' and naming ask_pipeworx as the alternative for live news. It also explains the parallel decomposition behavior, which distinguishes it from simpler lookup tools.

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

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

The description provides explicit when-to-use guidance, including examples ('compare X and Y's regulatory + financial exposure'), and explicit when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx.' It also names the required account tier and directs unsigned-in users to ask_pipeworx, plus advises against paid depth for non-paid tiers. This is exceptional routing guidance.

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

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

Annotations already indicate 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?

The description adds rich behavior beyond the readOnly/openWorld/idempotent annotations: it explains the cross-source fan-out, GDELT→GNews fallback, `sources_used`/`sources_failed` semantics, and edge cases like 'an empty section is a real "no data", not a bug' and 'a private company returns resolved:false with an explicit notes line.' This is exactly the kind of contextual disclosure the annotations do not cover.

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 it is front-loaded with purpose and usage signals before enumerating sources and return fields. The dense parentheticals are justified by the tool's complexity, and each clause conveys operational instructions. It could be better organized, but no sentence is filler.

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

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

With no output schema, the description carries the full burden of return-value disclosure. It lists all expected sections (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and explains failure semantics, fallback behavior, and input edge cases. There is no major missing piece an agent would need to guess.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by clarifying that `type` is interchangeable ('both are accepted and behave identically') and by providing concrete examples (AAPL, 0000320193, Moderna). This goes beyond the schema without being necessary to understand the 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 opens with concrete trigger phrases and states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, but it never names adjacent sibling tools like deep_research or compare_entities, so differentiation is partial.

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 tells the agent when to prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives user-phrasing examples. It does not state when not to use it or how it contrasts with specific sibling tools, so it stops short of a 5.

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?

Despite annotations already declaring readOnly/openWorld/idempotent/non-destructive behavior, the description adds rich behavioral detail: compatibility codes, unclassified legs never paired, skipped counters, gross-vs-net fees disclosure, and the meaning of null temporal alignment. This goes well 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 long and dense, but it is structurally organized into mode definitions, response fields, safety fields, and caveats. Some redundancy exists, such as restating temporal_alignment_unknown semantics twice, but most sentences carry substantive safety or usage information that earns their place.

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

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

With no output schema, the description must explain the response shape on its own, and it does: leg prices, top_spreads_pp, compatibility fields, skipped counters, fees, and temporal alignment semantics. For a complex two-venue comparison tool, this is unusually 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?

The input schema already describes all three parameters at 100% coverage. The description adds meaningful nuance beyond the schema by explaining the topic mode list, the override behavior of explicit ticker/slug, and that both modes share the same matching logic. This is valuable but the schema still carries the baseline burden.

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

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

The description clearly defines the tool as measuring cross-venue spread between Kalshi and Polymarket for the same resolving question, naming the specific venues and the comparison object. It does not explicitly name or distinguish against sibling tools like polymarket_arbitrage, so it is clear but lacks direct sibling differentiation.

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

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

The description provides explicit guidance on the two invocation modes (`topic` shortcuts vs explicit ticker/slug), explains that both run the same matcher, and warns that pre-mapped topics often return compatibility_warning. It gives clear context for mode selection but does not explicitly state when an alternative sibling tool should be preferred.

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?

The description goes well beyond the annotations, detailing multi-source cascade behavior, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit unresolved identifier reporting, and candidate-returning behavior for ambiguous matches. No contradiction exists with the readOnly/idempotent annotations.

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

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

The description is dense and front-loaded with the most important usage guidance, but it runs as one long unbroken paragraph with many nested clauses. All content is valuable, but clearer structuring would improve scannability without losing 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?

For a tool with no output schema, the description provides a remarkably complete picture: supported types, input formats, source behavior, ambiguity handling, unresolved identifier disclosure, and failure degradation. An agent has enough to invoke it correctly in varied scenarios.

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

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

Though schema coverage is 100%, the description adds essential semantic detail: what 'value' should contain for different types, the ISIN-to-LEI behavior, the warning to pass only the entity name and not a full noun phrase for bonds, and examples like 'AAPL' and 'metformin'.

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

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

The description clearly identifies the tool's function: resolving a user-spoken name to canonical identifiers required by other tools. It lists supported entity types and distinguishes this resolver role from profile/compare siblings by positioning it as the first step whenever an ID is needed.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also explains supported types, what inputs are accepted, and behavior when a name is ambiguous, making it clear when this tool is appropriate.

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

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

Annotations 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.