Hunter

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: return format (per-model score, confidence, signals, raw_response + combined view), cost implications for Anthropic, and that it's free for default model. No contradiction with annotations.

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

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

Single, front-loaded paragraph covering purpose, default behavior, API key note, and return format. Efficient but could be slightly more structured with bullet points for clarity.

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

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

For a 4-param tool with no output schema but rich annotations, the description adequately explains inputs, return structure, and cost. No missing critical details for effective agent invocation.

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

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

Schema description coverage is 100%, baseline 3. Description adds meaningful context: examples for 'entity', supported models list for 'models', purpose of '_apiKey' and 'context'. This clarifies usage beyond the schema.

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

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

The description uses specific verbs ('probe', 'score visibility') and clearly identifies the resource (LLMs' knowledge of an entity). It differentiates from siblings like 'deep_research' or 'ask_pipeworx' by focusing on visibility scoring for marketing audits.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Mentions default model and BYO key for Anthropic, but does not explicitly exclude other scenarios or mention alternatives.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool returns structured answers with stable pipeworx:// citation URIs, fills arguments automatically, works on every tier, and performs one fast call. It also notes it can route to live news, adding behavioral context not present in 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 long but well-structured and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). Each section earns its place: scope, examples, alternatives, and operational notes. It could be tightened slightly without losing value, but the length is justified for a central tool.

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

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

Given the lack of an output schema, the description sufficiently explains what the tool returns (structured answer with citation URIs) and provides operational context (speed, tier compatibility, routing to news). It also covers alternatives and limitations, making the description complete for a complex question-answering tool.

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

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

The schema fully documents the 'question' parameter and its aliases, so the baseline is 3. The description strengthens this by providing domain-specific examples (SEC filings, FDA data, weather) and clarifying what kinds of factual questions are appropriate, which adds meaning beyond the simple schema definition.

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

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

The description clearly states the tool answers factual questions by routing to one of 5,462 tools across verified sources, with a specific verb ('answers', 'routes') and resource. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, and by positioning itself as the default entry point.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-to-step-up ('Step up only when needed'), and names specific alternatives for grounded answers and broad multi-part questions. It also includes concrete examples of appropriate queries, making usage scope very clear.

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

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

The description goes well beyond the annotations by disclosing the beta nature, the dynamic candidate routing improvements, the current inactive state, and the fact that it 'falls back to nothing' yet remains fully functional. This adds critical operational context that annotations alone do not provide, with 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 front-loaded with 'Beta version of ask_pipeworx' and efficiently covers identity, current status, usage, and operational details in about 80 words. Every sentence contributes meaningful information with 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?

For a complex universal router, the description covers experimental status, equivalence to the stable version, usage guidance, and the comparison mechanism. However, it relies on familiarity with ask_pipeworx for the response shape and exact argument behavior, which is a reasonable assumption given the sibling relationship but prevents a perfect score.

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

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

The input schema provides 100% coverage with descriptions for all six parameters and their aliases, so the schema is self-sufficient. The description only mentions 'same arguments' without adding further detail, providing no additional meaning beyond what the schema already documents. 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 identifies this as a 'universal router' with the same 5,462 tools and response shape as ask_pipeworx, making its function unmistakable. It explicitly distinguishes itself from the sibling ask_pipeworx by being the beta/experimental version, so the purpose is both specific and differentiated.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives explicit when-to-use guidance and implies the stable alternative (ask_pipeworx) for non-experimental use, fully covering usage context.

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

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

Adds context beyond readOnlyHint by disclosing the extra LLM call, the refusal reason list, and the evidence-verbatim-quote behavior. No contradiction with annotations; the description provides significant non-obvious behavioral 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?

Description is long but every sentence earns its place; front-loaded with the core promise, followed by routing explanation, return/refusal formats, usage guidance, and cost comparison. No fluff.

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

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

Despite lacking an output schema, the description fully specifies the return shape on success and all failure modes, and covers routing, usage, and cost. It is complete for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100% with a single question parameter and aliases; description doesn't add new parameter detail but confirms natural language input. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

Clearly identifies as 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource (ask + grounded). Distinguishes from ask_pipeworx by emphasizing extraction only from tool result and explicit refusal behavior.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when to avoid ('prefer ask_pipeworx for casual lookups'), including the cost trade-off of one extra LLM call.

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

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

The description is extremely detailed, explaining how it resolves markets, classifies bets, fans out to data packs, returns evidence packets, and handles edge cases like low confidence, closed markets, wide spreads, and cancellation rules. This far exceeds the annotations (readOnlyHint, openWorldHint), providing comprehensive behavioral transparency.

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

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

The description is long but well-structured with clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence provides useful detail, but conciseness is slightly sacrificed for comprehensiveness. It earns a 4 for being structured and 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?

Given the tool's complexity, the description is thorough, covering inputs, behavior, outputs, edge cases, and safety. It compensates for the lack of an output schema by detailing response shapes, resolver contracts, and fallback mechanisms. The description is fully 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 all three parameters (market, depth, include_raw) described. The description adds context beyond the schema, e.g., 'include_raw: ... keeps responses under ~20KB' and explanations of market input types. This adds moderate value over the schema alone.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb 'Research' and the resource 'Polymarket bet', distinguishing it from sibling tools like deep_research (general) and polymarket_arbitrage (specific focus).

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also details input types and warns about low-confidence matches and closed markets. However, it lacks explicit when-not-to-use or alternative tools, hence a 4.

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: parallel call handles off-calendar fiscal years, results sorted by primary metric, returns citation URIs, replaces many lookups. 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?

Front-loaded with trigger phrases, then concise details. Every sentence adds value. No wasted words.

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

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

With only 2 params and no output schema, description fully covers what the tool does, how it behaves, and what to expect. 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%, but description adds significant meaning: for type it explains company vs drug data sources, for values it provides examples and constraints. Goes beyond schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It includes explicit trigger phrases like 'compare X and Y', distinguishing it from siblings like 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: 'ALWAYS PREFER over sequential single-pack lookups' and examples of when to use (e.g., 'which is bigger'). Also details what each type returns, aiding correct invocation.

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 with annotations providing readOnlyHint and idempotentHint, the description adds substantial behavioral detail: parallel decomposition across 5,462 tools, findings packet structure (evidence, confidence, gaps[], contradictions[], hop field), latency expectations (15-60s, up to ~90s), semantic excerpting, and specific citation_uri behavior. 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?

Though long, the description is densely informative and front-loaded with the critical account requirement. Each section (purpose, usage, behavior, latency) earns its place, but some sentences are over-packed and could be split for readability. Slight redundancy in emphasizing 'not open-web search' twice.

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

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

Given the tool's complexity and lack of output schema, the description compensates thoroughly: it explains the return format (findings packet, gaps, contradictions, hop field), performance characteristics, and prerequisites. It leaves little ambiguity about what to expect, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond schema by providing example questions, explaining depth tiers in more operational detail (gap recovery, lead chasing), and noting the paid requirement for 'thorough'. It enhances but doesn't fundamentally transform param 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's function: "Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call". It uses a specific verb ('research') and resource (Pipeworx structured data), and explicitly distinguishes from siblings, noting "this is NOT open-web search" and contrasting with ask_pipeworx for single lookups or current-news topics.

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 usage 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". Also gives conditions (account required, paid tier for thorough) and alternatives when not signed in, making when-to-use vs. when-not-to-use crystal clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that each result is ready to call directly with full schemas, no second lookup needed. No contradictions.

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

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

Description is front-loaded with purpose, then examples, then usage guidance. Some redundancy but all sentences add value. Could be slightly shorter but still concise.

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

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

No output schema, but description fully explains what is returned: top-N tools with names, descriptions, and full input schemas with examples. Sufficient for the agent 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?

Schema has 100% coverage with descriptions for each parameter. Description adds natural language examples and notes aliases, but mostly redundant with schema. Baseline 3 due to high coverage.

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

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

The description clearly states the tool finds tools by describing data or task, listing many specific domains (SEC filings, FDA drugs, etc.). It distinguishes from siblings by being the discovery tool to call first.

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 'Call this FIRST when you have many tools available and want to see the option set.' Implicitly when you know the tool, call directly. No explicit when-not or sibling names, 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds value by detailing the return content: email pattern, list with names, positions, departments, and confidence scores, which goes beyond what annotations provide.

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

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

Very concise: two sentences plus a useful example. Every part earns its place with no wasted words.

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

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

Given the tool has 5 parameters and no output schema, the description covers purpose, return content, and provides an example. It could mention pagination limits or confidence score interpretation, but overall it is fairly complete.

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

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

Schema coverage is 100%, so each parameter is already described. The description adds minimal extra meaning beyond the schema, only an example call. Baseline 3 is appropriate.

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

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

The description clearly states it finds email addresses for a domain on Hunter.io, specifying the verb and resource. It is specific but does not differentiate from the sibling tool email_finder, which may have overlapping functionality.

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

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

No explicit guidance on when to use this tool versus alternatives. The example implies usage for searching emails by domain, but no when-not-to or alternative suggestions are provided.

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 returns email, confidence score, position, and sources. No contradictions, but it could mention rate limits or API key dependency beyond schema.

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

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

The description is concise, front-loaded with the action, and includes a helpful example. Every sentence adds value with no wasted words.

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

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

For a simple tool with 4 parameters and no output schema, the description covers the key aspects: purpose, return values, and an example. It is 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?

Schema coverage is 100% with clear parameter descriptions. The description adds an example showing parameter usage, but doesn't significantly enhance meaning beyond what's already 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 the tool's action: finding the most likely professional email for a specific person at a domain on Hunter.io. It distinguishes from siblings like email_verifier (verifies) and domain_search (domain-level), 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 implies usage when you have a person's name and domain, and provides an example. While it doesn't explicitly mention alternatives or when not to use, the context is clear enough 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?

Annotations already indicate readOnlyHint, idempotentHint, and not destructive. The description adds valuable behavioral context: the types of checks performed (MX, SMTP, disposable, webmail) and the output format (status, result, confidence score). 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?

Two sentences plus an example, no wasted words. Information is front-loaded and easy to parse. 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?

Although there is no output schema, the description adequately explains what the tool returns (status, result, confidence score) and lists the verification checks. Annotations cover safety and idempotency. No gaps for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds example values and clarifies that the email is the target, but does not explain the _apiKey parameter beyond what the schema provides. Baseline 3 is appropriate as the description adds marginal semantic value.

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

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

The description clearly states the action ('Verify an email address') and the resource (Hunter.io). It enumerates specific checks (deliverability, MX records, SMTP, disposable/webmail) which distinguishes it from siblings like email_finder and domain_search.

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

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

The description implies use when an email's deliverability needs confirmation, but does not explicitly state when not to use or name alternatives. The sibling list provides context but the description itself lacks exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false, establishing safety. The description adds valuable behavioral context: it fans out across multiple sources, notes the patent source sunset with soft-fail behavior, and explains fallback mechanisms for news. This goes 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 well-structured with example queries upfront. It is somewhat long but every sentence adds value, covering purpose, usage, data sources, return format, and limitations. Could be slightly more concise, but the complexity justifies the length.

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

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

Given no output schema, the description thoroughly explains all data sources, return fields (with URIs), limitations (patent sunset, name unsupported), and fallback mechanisms. It also provides usage context relative to sibling tools. This is comprehensive for a complex tool.

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

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

Schema coverage is 100% with good parameter descriptions. The description reinforces that 'value' can be ticker or CIK and that names are not supported, which is already in the schema. It adds limited new semantic depth beyond what the schema provides, but it does clarify the exact formats (e.g., zero-padded CIK).

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

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

The description explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and returned fields. It clearly distinguishes from chaining single-pack lookups, making the tool's purpose unmistakable.

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

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

The description contains explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also warns that names are not supported and directs to use resolve_entity first, providing clear when-to-use and when-not-to-use criteria.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context about clearing sensitive data, which is valuable beyond annotations.

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

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

Two sentences, front-loaded with verb, no wasted words. Efficiently conveys all necessary 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 delete tool with one parameter and full annotations, the description covers purpose, usage, and pairing. No gaps present.

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 parameter description is clear. The description does not add extra meaning beyond what the schema provides.

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

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

The description clearly states the tool deletes a memory by key. It explicitly pairs with 'remember' and 'recall', distinguishing it from 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?

Provides clear when-to-use scenarios (stale context, task done, clear sensitive data) and references sibling tools. Lacks explicit when-not-to-use, but positive guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, making the tool's safety profile clear. The description adds behavioral details (fetches page, extracts content, emits markdown) but does not disclose potential limitations like handling of JavaScript-heavy sites or error conditions, which would have made it fully transparent.

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 well-structured sentences plus a bullet-like 'Useful for' list, front-loaded with the core purpose. Every sentence adds distinct information without redundancy or fluff.

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

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

Despite lacking an output schema, the description clearly states the output is a single text blob ready for deployment at site-root/llms.txt. It explains the extraction process sufficiently, and for a simple tool with 2 parameters, no further details are needed.

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 describes both parameters (url and max_links) completely. The description adds no extra meaning beyond the schema; it mentions 'for any URL' but does not elaborate on max_links. Thus, the description provides minimal added value over the structured parameter definitions.

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

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

The description clearly states the tool generates an llms.txt file for any URL, extracting title, description, and key links, and outputs standard markdown. It uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource and output format, distinguishing it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing a competitor. However, it does not mention when not to use the tool or provide alternatives from the sibling list, missing an opportunity to guide the agent away from inappropriate use.

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

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

Annotations already declare readOnly and idempotent; description adds useful return field details (id, type, etc.) 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 well-structured sentences; first states purpose and output, second gives usage context. No extraneous text.

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

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

Covers purpose, parameters implicitly via schema, return field list, and usage context. Sufficient for a simple list tool without output schema.

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

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

Parameter fully documented in schema (100% coverage); description does not add extra meaning to the parameter.

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

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

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Could mention alternatives but clear guidance.

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

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

Despite annotations being all false, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the human process ('The team reads digests daily and signal directly affects roadmap'). It also warns about consequence of reporting wrong server ('reporting it here only delays you'). This adds behavioral context far beyond annotations.

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

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

The description is moderately long but every sentence carries essential information: purpose, triggers, exclusions, content guidance, and rate-limit/quota context. It is front-loaded with the core action and structured logically.

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 feedback tool with no output schema and simple parameters, the description fully covers scope, constraints, and usage rules. It explains what to report, what not to report, and what to expect (daily digest, rate limit, free). 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?

The input schema already documents all parameters (100% coverage), but the description adds practical guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' directly informs the message parameter, and each use-case phrase maps to the type enum (bug, feature, data_gap, praise). This elevates it beyond schema descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the verb 'tell' and the resource 'Pipeworx team' with the scope of feedback. It distinguishes from all sibling tools (research, search, subscription tools) as the dedicated 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?

The description explicitly lists when to use: '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: tools from other MCP servers should be reported there, and tells users how to verify ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint = false. The description adds valuable context: data is aggregated from CF analytics-engine, no PII, caching behavior (5min-1h). This exceeds what annotations provide without contradiction.

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

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

The description is concise: two sentences followed by bullet points. Each sentence earns its place, with front-loaded purpose and efficient delivery of use cases, data source, and caching policy.

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

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

Given the tool's simplicity (one optional param, no output schema) and full annotation coverage, the description is complete. It explains what the tool returns, the data source, caching, and when to use it, leaving no critical 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 description coverage is 100% and already explains the window parameter and its trade-offs. The main description reiterates but does not add substantial new 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 what the tool does: returns trending data (top tools, top packs, total call volume) based on what other AI agents are calling on Pipeworx. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on usage statistics rather than querying or exploration.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case with demand). It does not explicitly state when not to use, but the given guidance is clear and contextually sufficient.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds extensive behavioral context: monotonicity checks, partition sum verification, similarity filtering, placeholder exclusion, and fill risk assessment. It explains when not to trade (realizable_edge_pp ≤ 0). 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 thorough but somewhat lengthy. It is well-structured, starting with the core action, then detailing each mode and sub-checks (semantic anchor, partition filter, fill check). Every sentence adds value, but the density might be overwhelming. A cleaner summary at the top would improve conciseness.

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 covers the response structure: opportunities array with gap_pp, suggested_trade, reasoning; partition_check object with sum_yes_prices, gap_from_1, etc. It also mentions fill check details. However, it could be more explicit about all response fields and their types. For a complex tool, it is largely complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by providing examples (e.g., 'fed-decision-may-2026'), explaining the difference between event and topic modes, and clarifying that 'topic' accepts seed questions. It 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage detection.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan... pass event for... pass topic for...' It recommends event for a specific market and topic for cross-event scanning. It also advises using polymarket_fill_risk for custom sizing, providing clear usage guidance and alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching strategy (1h at KV level keyed on all knobs), edge calculation details, slippage handling, diagnostic output for empty segments, and the Fed note about unreliable signal. 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 long but well-structured: front-loaded purpose, then segment details, tradeable-edge knobs, response structure. Every sentence provides value. Could be slightly more concise, but the complexity of the tool justifies the length.

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

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

With 9 parameters (0 required), no output schema, and multiple sibling tools, the description is remarkably complete. It explains the output structure (by_segment, fed_candidates, diagnostics), why segments may be empty, tradeable-edge knobs, and caching behavior. No gaps remain for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: e.g., for slippage_pp it explains Polymarket zero fees but typical 20-50bp slippage; for min_partition_leg_kelly it explains why standard min_kelly doesn't apply and how this knob works. All 9 parameters have enriched descriptions with usage 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?

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing the unique three-segment approach (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and specific use case 'what should I bet on today'.

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 addresses when to use the tool ('Built for "what should I bet on today"') and explains the three segments, including tradeable-edge knobs and Fed bets caveat. However, it does not explicitly state when NOT to use it or list alternative sibling tools for comparison, which would improve 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?

Adds significant behavioral context beyond annotations: explains response structure (tracked, expired, snapshot_dates), data sources (daily closes, not intraday), TTL limits, and snapshot gaps. 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?

Front-loaded with purpose, but somewhat verbose in parenthetical details. Every sentence adds value, though a slightly tighter structure could improve conciseness.

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?

Exceptionally complete for a tool with no output schema. Covers all response fields, limitations (TTL, gaps), and edge cases. Sufficient for agent to understand expectations.

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 parameter meaning by explaining days as lookback with defaults and clamping, and window as snapshot family. Provides extra context beyond schema descriptions.

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

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

Clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question. Distinguishes itself from 'polymarket_edges' by focusing on time-series tracking rather than current 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?

Implies usage for assessing edge age and decay through context like 'a fresh wide edge and a 3-week-old wide edge are different trades', but lacks explicit when-to-use or when-not-to-use guidance compared to siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond annotations: it explains the ladder walking, return of terms like verdict (clean|degraded|cannot_fill), and the risk of forced directional risk. This provides valuable context that annotations alone do not convey.

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

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

The description is relatively long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and uses formatting (capitalization, bullet-like structure) to enhance readability. While a bit verbose, every sentence adds value for the AI agent.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description provides a thorough explanation of all return values for both modes. It covers edge cases (thin legs, forced directional risk) and the dominant loss mode, making it sufficiently complete for an AI agent to understand and invoke correctly.

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

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

With 100% schema description coverage, the baseline is 3. However, the description adds significant extra meaning: it clarifies that market or event is required (not both), explains the default side for basket mode, and interprets size_usd differently for single-market vs basket. It also details what each mode returns, going beyond the schema.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It specifies the return fields for each mode, making it distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the consequences of not using it (unhedged directional position). This provides clear when-to-use and when-not-to-use guidance.

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

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

Adds rich behavioral context beyond annotations: explains safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), what happens when bet shapes are non-equivalent, and when events are semantically unrelated. No contradiction with annotations.

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

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

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, front-loaded with purpose. Appropriate length given the complexity of the tool.

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

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

No output schema, but description fully explains response format (leg-by-leg prices, top_spreads_pp, safety fields) and covers all edge cases like temporal misalignment and skipped comparisons. Complete for the tool's complexity.

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

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

100% schema coverage, so baseline 3. Description adds meaning by explaining the topic shortcuts, their auto-fetch behavior, and how explicit tickers override mapped defaults, providing contextual guidance beyond schema descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, specifying when the delta is a real signal. It distinguishes from siblings like polymarket_arbitrage by focusing on venue 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 describes two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, advising when not to rely on results. Provides clear context on when to use each mode.

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

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

Adds behavioral details beyond annotations: listing all keys when omitted, scoping to identifier, and pairing with other tools. No contradictions with annotations (readOnly, idempotent, non-destructive).

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 concise, well-structured sentences. Front-loaded with primary action, then usage context, then scope. 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?

Fully describes the tool's dual behavior (retrieve vs list), scoping, and relationship to remember/forget. Annotations cover safety, so no gaps remain.

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

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

Schema coverage is 100% with clear description for the single optional parameter. Description repeats this info, adding no extra semantic value beyond what 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?

Clearly states the tool retrieves a saved value or lists all keys, with distinct verb+resource. The mention of 'remember' and 'forget' distinguishes it from sibling tools.

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

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

Provides explicit examples of when to use (look up saved context like ticker, address, notes) and mentions scoping and pairing with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false, indicating safe, repeatable reads. The description adds useful behavioral details: the effect of mark_read on subsequent calls, the nature of the feed as persisted, and the data returned (source, citation_uri, raw payload). It does not disclose any negative behaviors but provides solid 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 concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value, covering the return data, filtering options, mark_read behavior, and a note on alternative access. No superfluous information.

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

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

Given no output schema, the description explains the return values (source, citation_uri, raw payload) and notes the feed is persisted. It covers key usage patterns (polling, filtering, mark_read). It does not mention error cases, rate limits, or maximum limit range (though that is in the schema). Overall, fairly complete for a tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the purpose of filtering by type and since, and notably clarifies the mark_read parameter (flagging events read so next call shows newer). It does not detail limit or unread_only, but the schema already covers their descriptions. The added context justifies a slightly higher score.

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: pulling fired events from a subscription feed and returning recent alerts. It specifies what each alert contains (source, citation_uri, raw payload) and distinguishes itself from other tools by focusing on alerts from the persisted feed, which is distinct from sibling tools like 'ai_visibility_check' or 'ask_pipeworx'.

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

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

The description provides good context, including filtering options (type, since, mark_read) and mentions that polling is acceptable. It also points to an alternative REST endpoint for scripts/dashboards. However, it lacks explicit guidance on when not to use this tool versus alternatives, such as when to use search_within or other retrieval tools.

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

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

The description details fan-out behavior, fallback logic (GDELT→GNews), soft-fails (USPTO PatentsView API sunset), and return structure. Annotations already declare readOnlyHint and idempotentHint, but description adds rich behavioral context beyond annotations.

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

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

The description is comprehensive and well-structured with examples first, followed by technical details. Slightly lengthy but efficient for the complexity; no wasted sentences.

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 structure (changes[] grouped by source, total_changes count, citation URIs). For a tool with 3 required params and complex external API logic, the description is fully 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%, but description adds significant meaning: explains date format options (ISO vs relative), acceptable values for each parameter, and clarifies that type only supports 'company'. This goes well beyond the schema descriptions.

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

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

The description clearly defines the tool as a 'change feed for a company' with specific query examples. It distinguishes from sibling 'entity_profile' by stating when to use each, achieving full purpose clarity.

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 provided: 'Use entity_profile instead when you want the static profile regardless of window.' Also gives examples of typical queries and recommends '30d' or '1m' for monitoring.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: persistence scope (authenticated vs anonymous), 24-hour retention for anonymous sessions, and scoping by identifier. 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?

Two sentences cover purpose, usage, and behavioral traits efficiently. No redundant statements; every sentence adds value.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers purpose, usage, persistence, and pairing with siblings. It is complete and actionable.

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. The description repeats key-value pair concept but does not add new semantic detail beyond the schema examples. 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 specifies the verb 'save' and the resource 'data the agent will need to reuse later', with explicit examples. It distinguishes from sibling tools like 'recall' and 'forget' by mentioning pairing.

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

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

The description provides explicit when-to-use guidance with concrete examples (e.g., resolved ticker, target address). It mentions pairing with recall and forget, indicating alternatives, though it does not explicitly state when not to use this tool.

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

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

While annotations already declare safe, read-only, idempotent behavior, the description adds substantial context: internal cascading lookups, specific return fields (CIK, RxCUI, citation URIs), input flexibility, and auto-disambiguation. These details go well beyond the structured metadata.

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

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

The description is well-structured and front-loaded. It opens with illustrative queries, then explains purpose, usage, and per-type details. Every sentence contributes value, and the length is appropriate for the tool's complexity.

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

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

Given two entity types and no output schema, the description fully specifies return values, source domains (SEC EDGAR, RxNorm), and citation URIs. It is complete enough for an agent to successfully select and invoke the tool.

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

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

The input schema provides 100% coverage with clear descriptions, but the description adds extra meaning by providing real-world examples, accepted formats (ticker, CIK, name), and per-type behavior such as auto-disambiguation. This enhances the schema without being redundant.

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+resource: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It includes concrete example queries and distinguishes itself from sibling tools by emphasizing that the resulting IDs are prerequisites for other 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?

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also frames the tool as replacing 2-3 manual lookups, which reinforces its role and context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. It also notes the first entity is treated as subject, which is helpful behavioral context.

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

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

The description is two sentences with no wasted words: first sentence defines action, second provides use case and return format. It is front-loaded and every sentence adds value.

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

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

Given no output schema, the description adequately describes the return (ranked list with score, confidence, signal density). It also clarifies entity ordering and the probe mechanism, making the tool 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 coverage is 100%, so baseline 3 applies. The description does not add parameter-specific details beyond what the schema provides, but that is acceptable given full schema documentation.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking them. This distinguishes it from the single-entity sibling ai_visibility_check and from compare_entities, which likely compares different dimensions.

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 targets competitive AI-marketing audits, providing a concrete use case. However, it does not explicitly contrast with alternatives like compare_entities or state when not to use it, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia may take 5-30s on first measurement, and sources_failed will be listed. No contradictions.

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

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

The description is thorough and well-structured, front-loading the composite purpose and use case. While slightly lengthy, every sentence provides essential information without redundancy.

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

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

Given no output schema, the description compensates by listing return fields (summary block, per-advisory details, links, alternative versions) and explaining partial failure behavior. It covers edge cases and timing, making the tool's behavior fully predictable.

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 clarifying that scoped packages are accepted and that version defaults to latest. This goes beyond the schema's own 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 specifies a composite check for npm packages covering license, advisories, bundle size, and more. It uses specific verbs ('scan', 'check') and clearly differentiates from sibling tools by naming the integrated services and the specific use case ('should I add this npm package').

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

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

The description explicitly states when to use: in response to questions about safety, popularity, or size of npm packages. It also provides an alternative: other ecosystems should use 'deps.dev:version' directly, and warns about NPM-only scope in v1.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds truncation behavior (200K char cap flagged), embedding model (BGE-base-en), similarity method (cosine), window size (500-char overlapping), and that offsets are returned. No contradictions. Lacks details on rate limits or auth, but sufficient.

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

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

Three sentences: each earns its place. Front-loaded with core capability, then usage benefits, then technical details. No redundancy or filler. Perfectly concise.

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

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

Given 3 params, no output schema, and annotations present, the description covers all necessary aspects: usage, behavior, limitations, pairing, and technical details. Nothing missing for an agent to use this tool effectively.

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

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

Schema covers all 3 parameters with descriptions. The description adds practical context: 'Pass the text you already pulled' for the text parameter, natural-language query examples for query, and the limit range (1-20). This enhances understanding beyond schema alone.

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

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

The description specifies 'semantic search INSIDE a fetched record', giving concrete examples (SEC 10-K, article) and a distinguishing pairing with sibling ask_pipeworx_grounded. The verb 'search' and resource 'fetched record' are clear, and the tool's niche is well-defined.

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 the record is too big to cram into the prompt — search_within saves context'. Also provides guidance on pairing: 'Pairs with ask_pipeworx_grounded'. This clearly delineates from alternatives.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: returns a new subscription id, requires OAuth, SMS cap, webhook auto-disabling, and HMAC signing. It does not clarify idempotency (whether duplicate calls create duplicate subscriptions), leaving a gap relative to the idempotentHint annotation.

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

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

The description is well-structured: purpose first, then prerequisites, supported types with examples, then delivery channels. It is slightly long but every sentence adds value. The information is front-loaded and organized logically.

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

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

For a tool with 3 params, nested objects, and no output schema, the description covers purpose, prerequisites, type-specific parameters, delivery options with limitations. It lacks discussion of error cases and idempotency, but overall is fairly complete for medium complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context beyond the schema: explains item codes for sec_8k, topic for polymarket_edge, and detailed delivery behaviors including webhook signing and auto-disable. This extra information justifies a score above baseline.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and distinguishes from sibling tools like list_subscriptions and unsubscribe. It specifies the resource (subscription) and action (create) with clear verb+resource structure.

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

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

The description provides usage context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery channels. However, it does not explicitly state when not to use this tool (e.g., for one-time alerts) or mention alternative tools like recent_alerts for pulling instead of subscribing.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds that it returns 'exact tool + argument shape' from live catalog, providing useful 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?

Description is slightly long (3 sentences) but front-loaded with example queries and efficient. No wasted words, though could be slightly tighter.

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 explains the kind of output (categorized examples with tool info). Complete enough for a simple onboarding 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 covers 'topic' with description; description adds examples of focus areas and usage guidance ('omit for cross-category spread'). Adds value beyond schema.

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

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

Description clearly states it returns category-bucketed example questions for onboarding, distinguishes from siblings like 'ask_pipeworx' and 'entity_profile' by being the first step for new users.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists example queries. Does not specify when not to use, but context makes that 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 indicate mutation, idempotent, not destructive. Description adds ownership enforcement and explains deactivation behavior (row deactivated, not deleted, historical events remain). 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?

Two sentences, front-loaded with core action, no redundant information. Every sentence provides essential context.

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

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

Tool is simple (1 required param, no output schema). Description fully covers purpose, parameter origin, ownership, and behavioral effect. No missing details.

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

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

Only one parameter with 100% schema coverage. Description adds value by specifying parameter origin ('returned by subscribe'), which helps the agent understand how to obtain the id.

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 'Cancel a subscription by id' using a specific verb and resource. It distinguishes from sibling tools like subscribe, list_subscriptions, and recent_alerts by mentioning ownership enforcement and deactivation.

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

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

Description provides context on when to use (cancel subscription with id) and includes ownership enforcement, implying user must own the subscription. It does not explicitly state when not to use or mention alternatives, but the guidance is sufficient for a simple tool.

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

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

Annotations already indicate safe read-only behavior (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds significant behavioral context: it reveals the two distinct verification pipelines (SEC EDGAR + XBRL for financial claims vs. grounded pipeline for others), mentions exact percent-delta math, and specifies the output includes verdict, actual value with citation, and reasoning. 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 comprehensive but slightly lengthy. It is well-structured with front-loaded examples and clear separation of financial vs. other claims. Every sentence provides useful information, though some redundancy could be trimmed (e.g., listing multiple example phrases).

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 claim types, two verification paths, no output schema), the description thoroughly explains the return values: five verdict types, grounded or structured actual value with pipeworx:// citation, and reasoning. It also mentions efficiency gains (replacing 4-6 calls), which helps the agent understand the tool's value proposition.

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?

Both parameters have full schema coverage. The description adds meaning beyond the schema: for 'claim', it provides example queries showing natural language; for 'tolerance_pct', it explains default behavior (implied by wording, capped at 5) and when to override (e.g., 1-2 for hallucination detection). This enriches the parameter 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 that the tool verifies natural-language claims against authoritative sources, with specific verb 'verify' and resource 'claim'. It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' and 'deep_research' by noting it replaces 4-6 sequential calls and handles two distinct verification pipelines (SEC EDGAR for financial claims, grounded pipeline for others).

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes when to use the tool and provides context on two verification paths, though it does not explicitly state when not to use it. The sibling list provides implicit alternatives.

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