Kegg

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: probing multiple LLMs, scoring methodology, default free model, BYO key for Anthropic with direct payment, and detailed return format including per-model and combined views. 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 two sentences. It front-loads the core purpose, then explains default behavior and optional functionality. Every sentence adds essential information, with no redundancy or fluff.

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

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

Given the tool's complexity (multiple models, optional parameters, scoring, no output schema), the description covers all critical aspects: what it does, default model, optional Anthropic probe, required entity parameter, optional context for disambiguation, and the return format per model plus combined view. It also lists use cases, making it 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%, so the baseline is 3. The description adds value by explaining the default model behavior, the purpose of the API key (BYO for Anthropic), and how the context parameter helps disambiguate. This goes beyond the schema descriptions.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for knowledge about a business/brand/product/topic') and clearly distinguishes the tool's purpose: scoring visibility (0-100) per model. It states the default model and return structure, making it distinct from siblings like 'scan_competitor_ai_presence' which likely focuses on competitive analysis rather than multi-model 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 explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It provides context on default model and optional Anthropic integration. However, it does not explicitly state when not to use this tool or list sibling alternatives by name, slightly reducing the score.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds context beyond annotations by explaining routing behavior, citation URIs, and 'one fast call' performance. It does not contradict any annotation and adds meaningful operational detail, though it could mention rate limits or error 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 but well-structured: it starts with a preference directive, gives examples, then lists alternatives. Every sentence adds value, and the examples make it actionable. It could be tightened slightly, but the organization is clear and front-loaded.

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

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

Given the tool's complexity (routing to thousands of sources), the description is remarkably complete. It covers what data domains are handled, provides examples, explains the output format (structured answer with citation URIs), and gives escalation paths. No output schema exists, but the description sufficiently explains return values.

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 parameters, including alias fields. The description adds examples of questions but does not provide additional semantic detail beyond the schema. Since the schema already documents the parameters well, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes questions to appropriate tools among 5,529 sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role clear.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and gives concrete examples. It also names alternatives (ask_pipeworx_grounded for grounded answers, deep_research for multi-part questions) and explains when to step up, which is excellent usage differentiation.

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 by disclosing that candidate routing improvements are enabled live only when under test, that no candidate is currently active, and that the tool is a full working router with no fallback. It also states the exact compatibility (same tools, arguments, response shape), which is valuable behavioral context beyond the read-only, open-world, 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 front-loaded with the core identity ('Beta version of ask_pipeworx') and every sentence adds unique information: status, usage, behavior, and fallback. It is detailed but not bloated, and the experimental specifics (retirement date, comparison purpose) earn 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?

For a low-complexity tool with one required parameter and no output schema, the description is complete: it explains the exact relationship to ask_pipeworx, the current runtime state, the intended use, and the absence of fallback. The annotations cover safety, and the description covers operational context sufficiently for an agent to decide and invoke.

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 six parameters and aliases, so the baseline of 3 applies. The description only says 'same arguments' without adding any new parameter-level semantics beyond what the schema already provides.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly contrasts itself with the stable router and explains its experimental routing purpose. However, it does not mention the sibling ask_pipeworx_grounded, so sibling differentiation is slightly incomplete.

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 direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no candidate active, matches ask_pipeworx exactly) and that results are compared against the stable router, which tells the agent when this tool is appropriate versus the stable alternative.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses significant behavioral traits: it performs an extra LLM call, returns an evidence quote, and provides explicit refusal reasons (not_in_source, no_tool_match, etc.). It also clarifies that the answer is extracted using ONLY the tool result, aligning with the readOnlyHint. 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 the description is relatively long, it is densely packed with essential information and front-loaded with the core purpose. Every sentence contributes value: usage guidance, output structure, refusal modes, and cost trade-off. No redundancy or filler.

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

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

The description is highly complete given the tool's complexity. It explains the internal routing, the exactly returned fields, all refusal reason enums, and even the cost implication. Since there is no output schema, this description fully compensates by detailing return values and edge cases, making it self-sufficient 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?

The schema provides 100% coverage of the parameter 'question' and its aliases, so the description does not need to elaborate. The description adds no extra parameter-specific semantics beyond what the schema already documents, making the baseline 3 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 identifies the tool as a 'hallucination-resistant answer mode' and explains its core function: routing a question to the appropriate tool and extracting an answer strictly from the tool result. It explicitly differentiates from sibling ask_pipeworx by highlighting the grounded extraction, evidence output, and refusal behavior, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: use when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. It also lists the alternative tool by name, satisfying the 'when/when-not' criterion.

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 into exceptional detail about behavioral traits: how it resolves markets, classifies bets, fans out to data packs, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, wide-spread handling, and cancellation rules. It aligns with annotations (readOnlyHint, openWorldHint, idempotentHint) and adds substantial context beyond them.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence provides valuable information; the length is justified by the tool's complexity. Slight deduction for being verbose 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 no output schema, the description thoroughly explains return values and edge cases (low-confidence matches, closed markets, wide spreads, cancellation rules). It covers safety considerations and provides enough detail for agents to handle all scenarios. Excellent completeness.

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

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

Schema description coverage is 100%, and the tool description adds significant meaning beyond the schema, such as explaining the 'depth' enum values ('quick = 2-3 evidence sources, thorough = full fan-out') and 'include_raw' effect on response size. This helps agents understand parameter trade-offs.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), distinguishing it from siblings by its single-call, comprehensive research nature.

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 given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not explicitly state when not to use it or offer alternatives, the provided context is clear and specific enough to guide appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds value by explaining the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and output format (paired data with citation URIs). No contradictions detected.

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

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

The description is detailed yet efficient, front-loaded with trigger phrases and key advantages. Slightly long but every sentence serves a purpose. Could be trimmed slightly but remains clear and well-organized.

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

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

Given no output schema, the description adequately explains return values (revenue, net income, etc. for companies; adverse-event counts, FDA approvals, trials for drugs) and provides citation information. Covers edge cases (off-calendar fiscal years) and replacement value (replaces 8-15 lookups).

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 enhances understanding by explaining the type enum with concrete examples (tickers/CIKs for company, drug names for drug), constraints (2-5 items), and behavior like sorting by primary metric so rank queries work intuitively.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases like 'compare X and Y' and 'rank these companies'. It distinguishes itself from siblings like entity_profile (single entity lookups) by emphasizing parallel comparison.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides concrete trigger phrases. It also explains when to use company vs drug type and how results are sorted for ranking queries.

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

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

Annotations declare safe read-only/idempotent behavior, and the description adds substantial behavioral context beyond those: account requirements, parallel facet decomposition, gaps[] that are never invented, fetchable citations, semantic excerpting, contradictions[] for certain depths, and expected latency (15-60s, up to ~90s). No contradiction with annotations is present.

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

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

The description is long, but every sentence earns its place. It opens with the most critical operational constraint (ACCOUNT REQUIRED) and then methodically covers use cases, alternatives, output format, depth semantics, and performance expectations. There is no filler or redundancy.

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

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

Despite having no output schema, the description fully explains the return value structure (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]) and covers failure modes (empty gaps for non-catalog topics). With rich annotations and two well-documented params, the description leaves no critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining that 'depth:"thorough" needs a paid plan', clarifying that the question can be 'Broad/multi-part is fine', and providing concrete examples. It also reinforces depth behavior already in the schema, which slightly reduces novelty.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, which is a specific verb+resource. It also explicitly differentiates from siblings by stating 'this is NOT open-web search' and by contrasting with ask_pipeworx for single lookups and breaking news.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even accounts for authentication state: 'If you are not signed in, use ask_pipeworx instead'. Depth selection guidance is also detailed.

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, idempotentHint true, destructiveHint false. Description adds that it returns top-N relevant tools with names, descriptions, and full input schemas, and that each result is ready to call directly. This explains the output behavior and convenience 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 concise with about 5 sentences, each adding essential information. It is well-structured: starts with purpose, lists domains, explains return value, and gives usage guidance. No unnecessary words.

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

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

For a discovery tool with no output schema, the description sufficiently explains what the tool returns (top-N tools with schemas) and how to use it. It covers the input, output, and usage context, making the tool fully understandable 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% with descriptions for all 6 parameters. The description adds value by explaining the query parameter with aliases and providing example queries ('analyze housing market trends', 'look up FDA drug approvals'), which helps the agent form correct inputs.

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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the first call to discover the option set.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to invoke 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 readOnly, openWorld, idempotent, non-destructive. Description adds context: parallel call across multiple sources, soft-fail for patents, sunset date, and return format 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?

The description is a single dense paragraph packing many details. While comprehensive, it could be better structured (e.g., bullet points) for 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 tool's complexity (multiple data sources, fallbacks, limitations), the description covers all key aspects: inputs, outputs, edge cases (patents sunset, name unsupported), and behavior.

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

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

Schema coverage is 100%, so description's repetition of parameter info is redundant but it adds value by clarifying that names are not supported and suggesting resolve_entity as an alternative.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of US public companies. It lists example queries and explicitly distinguishes from sibling tools like chaining single-pack lookups.

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

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

It explicitly states when to use (holistic view) and when not (names not supported, recommending resolve_entity first). Also notes to ALWAYS PREFER over alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it is 'keyless' (no API key) and returns KEGG IDs with descriptions, providing extra 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 three sentences plus a standalone 'Keyless.' which is efficient. Each sentence serves a purpose: purpose, domain context, examples, and auth info. No redundancy.

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

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

Given the tool is a simple search with 2 parameters and no output schema, the description explains the database options, query examples, and the return format (IDs with descriptions). It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this with concrete examples and a list of database values, making parameter usage clearer.

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 'Search KEGG by keyword' and provides specific examples of databases and queries, making the purpose unmistakable and distinct from sibling tools like get_entry or search_within.

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 explicitly lists acceptable databases and gives example queries, guiding when to use. However, it lacks explicit 'when not to use' or alternatives, though the context is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not significantly expand behavioral disclosure beyond annotations.

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

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

Two concise sentences, front-loaded with purpose and usage guidance. 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?

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, usage context, and parameter meaning.

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

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

Schema coverage is 100% and parameter description in schema is adequate. Description adds no additional semantics beyond 'by key'; 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 action 'Delete' and the resource 'memory by key', and distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and mentions alternative tools for other operations.

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 as false, so the safety profile is clear. The description adds that it fetches a page and emits markdown, but does not disclose network dependencies or potential latency, which would add value 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?

Three sentences with no wasted words: first sentence states purpose, second explains process, third lists use cases. Front-loaded and efficient.

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

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

Given two parameters, no output schema, and straightforward functionality, the description fully covers what the tool does, its inputs, and its output (a text blob ready for deployment). No gaps.

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

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

Schema coverage is 100% with both parameters described in the input schema. The description does not add new information beyond what the schema already provides (e.g., default and max for max_links are in the schema). Baseline 3 is appropriate.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file'), and clearly states the goal of enabling AI crawlers to index sites. It distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

The description explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), providing clear context for when to use. However, it does not mention when NOT to use or compare to alternatives, missing full exclusion 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds keyless authentication requirement and specifies the return format (parsed fields plus raw text), which are behavioral traits 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?

Three sentences with zero waste: first states purpose, second provides examples, third gives usage guidance. Information is front-loaded and well-organized.

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

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

For a single-parameter tool with no output schema, the description covers purpose, parameter examples, return value overview, and usage prerequisite, making it fully informative.

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 valuable examples of ID formats and instructs to use find first, enriching the meaning beyond the schema's description.

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

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

Clearly states verb (fetch), resource (KEGG flat-file entry), and scope (by ID). Distinguishes from sibling 'find' by advising to use find first to discover IDs.

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 'Use find first to discover IDs' as a prerequisite, providing clear when-to-use guidance. Implicitly defines when not to use (without a known ID).

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 as false. The description adds value by noting the result cap and truncated flag, which are behavioral traits beyond annotations. 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 two concise sentences with no fluff. It front-loads the core purpose and follows with usage guidance and constraints. 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 tool has one simple parameter, no output schema, and clear annotations, the description adequately covers the return format (id+description), capacity limit (100), and flags. No significant gaps remain.

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

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

Schema coverage is 100% with a clear description of the 'database' parameter. The description adds examples ('pathway', 'drug') and clarifies that the output includes id and description, which enhances semantics 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 'List all entries in a KEGG database (id + description)', using a specific verb and resource. It distinguishes the tool from sibling tools by specifying KEGG databases, a unique domain among the listed 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 provides examples of when to use (enumerating pathways, drugs, organisms) and mentions the 100-result cap with a truncated flag. It does not explicitly state when not to use or name alternatives, but the context is sufficient for an agent to decide.

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

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

Description adds value beyond annotations by listing specific return fields (id, type, params, etc.) and implying read-only behavior. Annotations already indicate readOnlyHint and non-destructive, so 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?

Two sentences: first states purpose and output, second gives usage guidance. No redundant 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 simple list tool with one optional parameter and no output schema, the description adequately covers return fields and usage, making it complete.

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

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

Schema coverage is 100% with one parameter described. The description does not add new semantic meaning about the parameter beyond what's in 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly suggests using the tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when 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?

Even though annotations are all false (no read-only/destructive hints), the description discloses the claim_token mechanism, rate limits ('Rate-limited to 5 per identifier per day'), quota impact, and that 'The team reads digests daily and signal directly affects roadmap.' This goes far beyond the structured annotations.

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

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

The description is longer than one sentence but every clause adds critical behavioral or usage detail—no filler. It is front-loaded with purpose and then flows into usage rules, token mechanics, and limits, making it dense but well-organized.

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

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

Given the lack of an output schema, the description explains the return behavior (claim_token), how to retrieve resolution status, and the human workflow behind the feedback. It covers caveats about cross-server feedback and message content, making it fully self-contained for an agent to use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical guidance on claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs users to 'Describe the issue in terms of Pipeworx tools/packs,' adding value beyond the schema's field definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which precisely states the tool's action and target. It clearly differentiates from all sibling research/subscription tools by being the only feedback channel.

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 explicitly defines trigger conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion rule: not for other MCP servers, and directs users to file with that server 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?

Goes beyond annotations by explaining data source (CF analytics-engine), privacy (no PII), and caching (5min-1h).

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

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

Concise, well-structured with bullet points and front-loaded purpose. Every sentence contributes.

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?

Fully covers what the tool does, returns, data source, caching, and use cases. No gaps given simplicity and annotations.

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

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

Schema has full coverage, and description adds nuanced meaning for window values ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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 returns top tools, packs, and call volume over a window, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Provides three explicit use cases, but does not mention when not to use or alternatives, though the siblings list 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: scanning scope (top ~200 markets), partition checks (threshold >3pp), similarity filter (Jaccard ≥0.30), placeholder filter, fill check against live CLOB depth, and reference to another tool for custom sizing. No contradictions.

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

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

The description is front-loaded with the purpose and mode overview. It is detailed but not overly verbose. Some sentences (e.g., the fill check details) could be condensed, but the structure is logical and easy to follow.

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[], gap_pp, suggested_trade, etc.) and covers all edge cases (low similarity, placeholder filters, fill check). It also references another tool for custom sizing, making it self-contained for an agent.

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

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

Schema description coverage is 100% (both event and topic described). The description adds meaning beyond schema: event accepts slug or full URL, topic is a seed question, and explains when to use each mode with concrete examples.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb and resource, distinguishing it from siblings like polymarket_edges (edge detection) and polymarket_fill_risk (fill risk analysis).

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

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

Explicitly provides when to use each mode: 'Call with NO args for a trending_scan... pass `event` for... or `topic` for...' Recommends event mode for specific markets, topic for cross-event scanning, and warns against trading when realizable_edge_pp ≤ 0. Clear alternatives and exclusions.

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

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

The description discloses several behavioral traits beyond annotations: caching ('Cached 1h at the KV level'), response structure with diagnostics ('_diagnostics{...filter_skips} so callers can see WHY a segment is empty'), and edge computation details (Kelly fraction caps at 0.25, slippage subtraction). The readOnlyHint and idempotentHint are already in annotations, so the description adds useful operational context without contradiction.

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

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

The description is excessively long and dense, presenting a wall of text without clear structure. It covers multiple segments, response fields, and edge computation details in a single paragraph. While the content is valuable, it would benefit from breaking into sections (e.g., Overview, Model Families, Filtering, Response) to improve readability. 2 because overlong and unstructured.

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 fairly complete. It explains the three response segments, the fed_note, diagnostics, and the tradeable-edge knobs. It even details edge computation and caching. The missing output schema is partially compensated by the description's detailed explanation of what each response element contains. Score 4 because it covers most aspects an agent would need to understand the tool's behavior.

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

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

All 9 parameters are documented in the input schema with descriptions, so the baseline is 3. The description adds some value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and providing behavioral context (e.g., 'min_kelly never filters them' for partition arbs). However, the parameter descriptions in the schema are already comprehensive, so the description's addition is marginal.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price. Built for "what should I bet on today"'. It identifies the specific resource (Polymarket markets) and action (return opportunities with edge). The purpose is well-differentiated from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 the tool's use case: discovering opportunities without paging hundreds of markets. However, it does not explicitly state when to avoid this tool or suggest alternatives. Given the extensive sibling list, explicit guidance on when to use polymarket_arbitrage vs this tool would improve clarity. The description implies it is the primary edge discovery 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?

The description adds significant behavioral context beyond annotations: limitations (60-day snapshot TTL, data gaps, decay computed from daily closes, not intraday), and nuances about snapshot generation (cache-miss dependency). Annotations already declare readOnly, idempotent, openWorld, and non-destructive, and the description aligns with them while providing rich 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?

The description is lengthy but well-structured: purpose first, then response structure, then limits. Every sentence provides necessary information without repetition. It earns its length given the complexity of telemetry data and absence of output schema.

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 (tracked[], expired[], snapshot_dates[]) with detailed field semantics and computational methods. It also covers data freshness and limitations, making the tool fully understandable without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating default values (14 days, '1wk' window), maximum clamp (30 days), and explaining that 'window' refers to snapshot family. It also explicitly lists response fields and their meanings, compensating for the missing output schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings by focusing on historical persistence, with a concrete example differentiating fresh vs. old wide edges.

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

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

The description explains when to use the tool (to get historical edge persistence and decay) and provides an example that guides interpretation. While it does not explicitly list when not to use or name alternatives, the context from sibling tools and the clear purpose make usage fairly clear.

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

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

Beyond annotations (readOnlyHint, etc.), the description reveals detailed behavior: walking the ladder, returning specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), basket-mode nuances (theoretical vs realizable sum, capture ratio, forced directional risk), and warnings about unfilled partial baskets. 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 structured with clear sections (SINGLE-MARKET, BASKET) and a usage guidance paragraph. While lengthy, the detail is warranted for a complex tool with two modes. Minor redundancy could be trimmed, 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?

With no output schema, the description fully covers return values for both modes, including verdicts, thin legs, forced directional risk, and max clean notional. It also addresses edge cases and risks, making it self-contained for agent decision-making.

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

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

Schema coverage is 100%, but the description adds significant meaning: clarifies mode selection via market vs event, explains size_usd as settlement notional for baskets, and default side logic. This goes beyond schema descriptions, enhancing agent understanding.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth, distinguishing two modes (single-market and basket). This specificity differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges, which are for generating signals or listing edges.

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

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

The description explicitly instructs to use this tool before acting on arbitrage signals or trades above $500, and explains the risk of partial basket fills converting arb into directional positions. This provides clear when-to-use and when-not-to guidance, referencing alternatives implicitly.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are already present. The description goes far beyond by detailing output structure, safety fields, examples of invalid spreads, and counters for skipped comparisons. No contradiction with annotations.

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

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

The description is fairly long but every sentence adds value. It is front-loaded: first sentence states purpose, then immediately introduces modes and safety. Could be slightly more concise, but not verbose.

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

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

Complex tool with no output schema; description compensates by detailing response structure (leg-by-leg prices, matched spreads, top_spreads_pp) and safety fields. Covers modes, compatibility, temporal alignment, skipped types. Sets realistic expectations that most pre-mapped topics are not tradeable. Complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: explains the two modes, all ten pre-mapped shortcuts, and how explicit parameters work. Schema descriptions are brief; the tool description clarifies usage and allowed values.

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

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

The description clearly states the tool's purpose as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings (none of which offer cross-venue spread comparison) with specific verb+resource+scope.

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

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

Explicitly describes two modes (topic vs explicit tickers) and when to use each. Provides safety fields and warns that most pre-mapped topics return compatibility warnings, guiding when not to trust results (e.g., temporal misalignment, incompatible bet shapes).

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 scoping context (anonymous IP, BYO key hash, account ID) beyond annotations. No contradictions with readOnlyHint, idempotentHint, destructiveHint.

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

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

Every sentence adds value: two modes, usage examples, scoping, pairing with other tools. No wasted words, front-loaded with main action.

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

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

Given no output schema, description could mention return format (e.g., string value or array of keys). But it's complete enough for its simplicity; minor gap.

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 already describes the 'key' parameter with 100% coverage. Description adds that omitting key lists all keys, matching schema's 'omit to list all keys'. Baseline 3 is appropriate; description provides marginal extra context.

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 retrieves a saved value by key or lists all keys when key is omitted. Distinguishes from siblings like 'remember' and 'forget'.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Gives examples like target ticker, address. Pairs with remember/forget. Could be more explicit about when not to use but still 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?

Adds behavioral details beyond annotations: mark_read effect, returned fields (source, citation_uri, payload). No contradiction with readOnlyHint or destructiveHint.

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

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

Four focused sentences, no fluff, logical flow: purpose, return fields, filtering, polling. Highly concise yet informative.

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

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

Covers return format, filtering, read-state management, and alternative access. No output schema needed; description adequately explains 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?

Schema coverage is 100%, but description adds examples (sec_8k), format (ISO timestamp), and mark_read behavior. Adds value beyond schema.

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

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

Clearly states 'Pull fired events from your subscription feed' with specific verb and resource. Distinguishes from sibling tools like list_subscriptions, subscribe, etc.

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

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

Provides filtering guidance (type, since) and polling advice. Mentions alternative endpoint for scripts/dashboards, but lacks explicit when-not-to-use comparisons.

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

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

Describes calls to SEC EDGAR, GDELT/GNews, USPTO, soft-failure for patents, and return format (changes[], total_changes, citation URIs). Annotations already indicate safety; description adds rich behavioral context.

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

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

Dense but well-structured paragraph with example queries, technical details, and clear separation of concerns. Every sentence provides unique information.

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

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

No output schema, but description explains return structure (changes[], total_changes, citation URIs). Covers all parameters, fallbacks, and limitations (patents soft-fail). Complete for an information retrieval tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining `since` accepts ISO or relative with examples, `value` as ticker/CIK, and typical monitoring window suggestion.

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 a change feed for a company over a recent window, with example queries. It distinguishes from the sibling `entity_profile` by explicitly contrasting use cases.

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

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

Provides explicit guidance on when to use (change feed queries) and when to use `entity_profile` instead. Also explains fallback behavior between GDELT and GNews.

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 behavioral context beyond annotations: key-value storage, scoping by identifier, and persistence differences (authenticated vs anonymous 24h). Annotations are idempotentHint=true, and description confirms idempotent behavior. 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 (3 sentences) with a clear front-loaded purpose, then usage guidelines, then technical details. Every sentence adds value with zero 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?

Given no output schema, the description explains behavior and storage semantics thoroughly. It could mention return value or error handling, but covers the core functionality completely for a storage tool.

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

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

Schema coverage is 100%, and the description adds real-world examples for keys and values, enhancing understanding. While schema already documents params, the examples provide added semantic clarity.

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 ('Save') and resource ('data the agent will need to reuse later'), with examples of use cases. It also distinguishes from sibling tools recall and forget, meeting the highest standard.

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

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

The description explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall and forget for complementary actions. It also provides context on scoping and persistence, guiding the agent effectively.

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 readOnly/openWorld/idempotent, and description adds meaningful behavior: it 'cascades through several lookup endpoints internally,' 'degrades gracefully' (EDGAR still returns if GLEIF/OpenFIGI unavailable), explicitly returns unresolved identifiers under `unresolved`, and labels identifiers with source. This goes well beyond the annotations.

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

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

The description is dense but well-structured, front-loading examples and purpose before details. It is long but virtually every sentence adds technical value (graceful degradation, unresolved field, internal cascading). Could be tightened slightly 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?

Despite lacking an output schema, the description fully describes the tool's scope, input variations, output identifiers, degradation behavior, and the unresolved field. It also notes the tool replaces multiple manual lookups, giving the agent a clear mental model. For a two-parameter tool with this complexity, 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% with clear descriptions, but the description enriches semantics with accepted input forms: ticker/CIK/name for company, brand/generic for drug, plus examples like AAPL, 0000320193, ozempic. It also clarifies what each type resolves to (CIK+ticker+LEI+FIGI, RxCUI+ingredient+brand).

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 query examples, then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' — a specific verb+resource+outcome. It clearly distinguishes from siblings like find or entity_profile by framing resolve_entity as the identity-lookup precursor.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID' and notes it 'replaces 2-3 manual lookups.' It does not explicitly name alternative tools or state when not to use, but the 'Use FIRST' directive provides strong contextual guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with per-entity metrics. 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 two sentences plus a usage note, front-loading the main action. Every sentence adds value, with no redundant or filler content.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers the key aspects, though it could mention error handling or what happens when entities are unrecognized. Still sufficient for an agent.

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

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

Schema coverage is 100% and the description adds critical context: first entity is treated as 'subject', models have defaults and prerequisites (e.g., Anthropic API key), and context disambiguates. This significantly enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. It distinguishes from the sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking.

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 case ('competitive AI-marketing audits') and a concrete example. It implies when to use but does not explicitly state when to avoid or provide alternative tool names beyond the mention of ai_visibility_check in the flow.

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 crucial behavioral details about partial failures and timing (bundlephobia's first measurement takes 5-30s, sources_failed list), which go beyond annotation coverage and help set agent expectations.

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 concise paragraph that front-loads the core purpose and then elaborates on details. It is efficient with no wasted words, though it could be broken into bullet points for 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 no output schema, the description thoroughly explains the return values (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases (failure modes, ecosystem limits). This makes the tool fully understandable 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 the description does not need to explain parameters; it adds context about the return summary block but does not enhance parameter meaning. 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 performs a composite check for evaluating whether to add an npm package, specifying data sources (deps.dev and bundlephobia) and the exact purpose. It distinguishes itself from sibling tools, which are unrelated to dependency scanning.

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

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

Explicitly states when to use ('is X safe / popular / small', 'what does adding lodash cost me') and provides a clear exclusion ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), effectively guiding agent selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant behavioral details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char truncation with flagging, and character offsets for verification. No contradictions with annotations.

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

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

The description is a single dense paragraph with no wasted words. Each sentence serves a purpose: core function, example, usage guidance, and technical details. Well front-loaded.

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

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

Despite lacking an output schema, the description details the return value (top-N passages with offsets and scores). It covers edge cases (truncation), tool model details, and integration with siblings. Complete for a medium-complexity tool.

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

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

Schema coverage is 100% with three parameters described. The description goes further: explains text max size and truncation, limit default and range (1-20), and provides query examples. This adds 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 performs semantic search inside a fetched record, using input text and natural-language query. It distinguishes from sibling tools like ask_pipeworx_grounded and find by specifying it operates on already-retrieved content, returning passages with offsets and scores. The verb 'search within' plus resource is precise.

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

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

The description explicitly recommends using the tool when records are too large for prompts and pairs it with ask_pipeworx_grounded for grounding. While it does not list exclusions or alternatives beyond that, the usage context is clearly stated.

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 provide idempotentHint=true and destructiveHint=false, but the description adds important behavioral details: OAuth requirement, phone verification, SMS cap of 10/day, webhook auto-disable after 10 failures, and one-time return of webhook secret. These go beyond annotations and help the agent understand side effects and constraints.

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

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

The description is front-loaded with the core action and return type, followed by requirements, supported types, and delivery details. Although lengthy, the structure is logical and each sentence adds value. Minor redundancy in repeating constraints across delivery channels, but overall well-organized.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is remarkably complete. It covers all parameter types with examples, explains delivery channel quirks, mentions the return value (subscription id), and highlights important constraints (authentication, verification, rate limits, auto-disable). No major gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning. For each supported type, it provides concrete parameter examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}'). For delivery, it explains verification and rate limits. This additional context helps the agent construct correct parameter values.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream.' This uses a specific verb ('Create') and resource ('proactive monitoring subscription'), clearly stating the tool's purpose. It also mentions 'Returns the new subscription id,' which clarifies the output. Among sibling tools (list_subscriptions, recent_alerts, unsubscribe), this description uniquely identifies the create action.

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

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

The description provides clear context for using the tool, including prerequisites ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channel options. However, it does not explicitly compare to alternatives or state when not to use this tool. Since the purpose is straightforward (creating subscriptions vs. listing or unsubscribing), the guidance is adequate but not exhaustive.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds that it returns category-bucketed examples with tool+argument shapes, and uses live catalog. 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?

Packs substantial information (categories, usage, return structure) into a flowing sentence. Slightly long but efficient, with clear front-loading of intent.

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

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

For a simple tool with one optional param and no output schema, the description fully covers what the tool does, what it returns, and how to use it. No gaps.

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

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

The only parameter (topic) has full schema coverage (100%). Description adds meaning: enumerates valid values, explains behavior when omitted vs. specified, and how it focuses 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's purpose: an onboarding entry point that returns example questions across categories, with specific tool+argument shapes. It distinguishes from siblings like ask_pipeworx 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?

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to use optional topic parameter. Missing explicit when-not-to-use, but clear enough.

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 non-read-only, idempotent, and non-destructive. The description adds value by disclosing that the operation deactivates rather than deletes, preserving historical events. 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 three concise sentences that front-load the core action ('Cancel a subscription by id') and then add key constraints and behavior. No extraneous 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 simple cancellation tool with one parameter, the description provides sufficient context: what it does, ownership constraint, side effects (deactivation), and relation to 'recent_alerts'. The annotations cover safety traits. Complete for an agent's needs.

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

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

The input schema has full coverage for the single 'id' parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds contextual ownership enforcement but does not provide additional parameter-level semantics 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 cancels a subscription by ID, using a specific verb ('Cancel') and resource ('subscription'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), which tells the agent when the tool is usable. It also mentions that the row is deactivated rather than deleted, linking to 'recent_alerts' for historical data. However, it does not explicitly state 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 mark the tool as readOnly, openWorld, idempotent, non-destructive. The description adds valuable post-verification behavior: the distinction between could_not_verify (check did not happen, must not be used as evidence) and unsupported (no source exists), plus the presence of verification_error with stage/detail. It also discloses the automatic fallback pipeline and citation mechanics, going well beyond the annotations.

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

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

The description is longer than average but every sentence earns its place: triggers, use cases, routing, verdicts, error semantics, and efficiency note. It is front-loaded with examples and ends with a clear 'IMPORTANT' caveat. Structure is logical, though slightly dense for a casual reader.

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 (routing, verdict types, error states) and the absence of an output schema, the description fully covers return values, evidence format, and failure semantics. It explains the difference between could_not_verify and unsupported, which is critical for agent decision-making. No gaps remain.

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

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

Even though the schema covers 100% of parameters with descriptions, the tool description enriches both. For claim, it provides realistic examples. For tolerance_pct, it explains the override semantics and gives a use case (1–2 for hallucination detection) and a default cap of 5%. This adds meaning beyond the bare 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 opens with concrete natural-language triggers ("Is it true that…", "fact check") and specifies the action: natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by stating it's for verifying factual correctness and even notes it replaces multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives a detailed breakdown of financial vs. other claims and the routing behavior. No explicit exclusions for when not to use, but the context is strong enough to infer boundaries.

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