Nist Standards

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavior: cost implications (free vs BYO key), return structure (per-model scores, confidence, signals, raw_response, combined view), and the probing mechanism. No contradiction detected.

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

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

The description is a single, well-structured paragraph of four sentences. It front-loads the core action and outcome, then provides details on defaults and return values. Every sentence adds value with no redundancy.

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

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

Given the four parameters and no output schema, the description covers the return structure (per-model fields and combined view) and use cases. However, it could be more explicit about the combined view format and any error handling or rate-limit information.

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

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

Schema description coverage is 100%, but the description adds context beyond: 'context' helps disambiguate, '_apiKey' is passed straight through, and 'models' defaults to workers-ai. This enhances understanding beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('Probe', 'score') and resource ('LLMs') to clearly state the tool's function. It distinguishes from siblings by highlighting the visibility scoring aspect, which is unique among tools like 'scan_competitor_ai_presence' 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 clear contexts like 'AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains the default model vs BYO key for Anthropic. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'scan_competitor_ai_presence'.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds behavioral context: 'returns the structured answer with stable pipeworx:// citation URIs', 'works on every tier, one fast call', and 'routes the question to the right one of 5,529 tools'. This goes beyond annotations without contradicting them.

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

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

The description is long but information-dense, with each sentence earning its place. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH'), followed by domains, examples, alternatives, and clarifications. Slightly verbose, but lacks redundancy and is well-organized.

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

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

Given the tool's scope (routing across thousands of sources), the description is remarkably complete. It covers purpose, usage triggers, example queries, distinction from siblings, default-entry behavior, and even notes breaking-news handling. There is no output schema, but the description sufficiently describes return outcome ('structured answer with citations').

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 six parameters being aliases for 'question'. The description itself does not elaborate on parameter syntax or constraints, but it provides numerous examples ('current US unemployment rate', 'Apple's latest 10-K') that implicitly clarify usage. This is adequate given the simple single-question schema, but adds no new parameter-specific details.

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

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

The description explicitly states the tool's purpose: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists specific domains. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The verb 'routes' and resource '5,529 tools across 1455 verified sources' clearly define what it does.

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

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

Provides explicit when-to-use guidance: 'START HERE for most questions', 'Use whenever the user asks...', and step-up alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. Also clarifies breaking-news handling. This fully covers 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?

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds important behavioral context: beta status, candidate routing improvements being enabled live, current inactive state, and reassurance that it is a full working router. 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 four sentences, each providing useful information: beta identity, current state, usage direction, and reassurance. While slightly verbose, no sentence is wasted and the structure is logical.

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

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

The description provides all essential context for an agent to invoke the tool: what it does, how it differs from stable ask_pipeworx, current behavior (matches stable), and when to use it. The response shape is inherited from ask_pipeworx, so no output schema is 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?

The input schema has 100% coverage, documenting the 'question' parameter and five aliases. The description adds no parameter-specific information, but the schema fully explains the single semantic input, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing improvements, making its 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 explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It gives clear context for when to use it, but does not explicitly state when not to use it (e.g., for stable/production needs), though this is implied.

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

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

The description goes well beyond the annotations by disclosing the tool's refusal behavior with a detailed refusal_reason enum, the exact output shape (answer, evidence, confidence, etc.), and the constraint of using ONLY the tool result content. It also flags the extra LLM call cost, which is important behavioral context not present in annotations. No contradiction with readOnlyHint or idempotentHint.

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

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

The description is information-dense but well-structured with a clear success/refusal dichotomy, concrete examples, and a final cost trade-off. Every sentence earns its place, and the most critical cues (grounded, high-stakes, refusal reasons) are front-loaded. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (routing across 5,529 tools, refusal handling, output shape), the description is remarkably complete. It covers the output schema, refusal reasons, use-case guidance, and cost trade-off. Missing a small amount of operational detail (e.g., exact confidence scoring semantics) but no output schema exists, and the description compensates well with the full return shape description.

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

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

Schema coverage is 100% and all parameters are aliases for the same 'question' string, which the schema already documents well. The description adds context about the question being in natural language and how it is routed, but does not add significant new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific verb (EXTRACTS) and resource scope (tools across 1455 sources). It distinguishes itself from the sibling ask_pipeworx by noting the same routing but grounded extraction and refusal behavior, and explicitly names the alternative for casual lookups.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with examples like financial verdicts and legal claims. It also gives a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups' and explains the cost trade-off (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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: market resolution, classification, fan-out, response shape details, resolver contract, parent event extraction, news fields, safety short-circuits, and cancellation rule risk. This far exceeds what annotations provide.

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

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

The description is very long and dense, containing multiple paragraphs with detailed examples and edge cases. While the first sentence front-loads the main purpose, the overall verbosity reduces conciseness. It could be trimmed while retaining essential information.

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

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

Despite lacking an output schema, the description comprehensively explains response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and cancellation rules. It covers all expected behaviors and edge cases, making the tool fully understandable without external documentation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value beyond schema by elaborating on the 'depth' parameter (quick vs thorough) and 'include_raw' parameter (when to use true/false). It also confirms the 'market' parameter accepts multiple formats, which is already in the schema description but is reinforced.

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

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

The description starts with a clear verb+resource combination: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explicitly states what the tool does and distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on research for a specific bet.

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

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

The description provides explicit usage cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples of fan-out and classifiers. While it does not explicitly state when not to use, it offers clear context and safety notes that guide appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

Well-structured with front-loaded examples and clear explanations. Some slight redundancy (e.g., 'side-by-side comparison' and 'compare entities'), but overall concise and easy to parse. 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?

No output schema, but description mentions return of 'paired data' and citation URIs. Explains entity types and sources adequately. Could be more specific about the format of the paired data, but sufficient for an agent to understand the output.

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

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

Input schema has 100% coverage with parameter descriptions, but the description adds crucial semantics: for 'type' it explains the data sources and for 'values' it specifies tickers/CIKs for companies and drug names, with concrete examples. This significantly aids correct invocation.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific example triggers like 'Compare X and Y' and 'X vs Y'. It distinguishes itself from sequential single-entity lookups, directly addressing sibling tools 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 on when to use: for comparison queries, ranking, head-to-head. Includes a strong recommendation to prefer over sequential lookups. Provides examples of user intents that trigger this tool, and specifies constraints (2-5 entities).

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

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

The description adds rich behavioral context beyond the annotations: account/paywall requirements, the gaps[] policy ('never invented'), guarantee that returned citations are always fetchable, semantic excerpting of long records, timing expectations (15-60s, up to ~90s), and contradictions[] 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?

The description is dense, wrapping many clauses into a few long sentences. It is front-loaded with critical constraints (account requirement, alternative tool), but it could be restructured into bullets for easier parsing. Every sentence carries value, but the overall length reduces 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?

With no output schema, the description fully covers return semantics: findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and timing. It also covers prerequisites and alternatives, making the complete usage context available.

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

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

Schema coverage is 100% and the schema already details the depth enum, so the baseline is 3. The description adds helpful framing like 'multi-step questions resolve in one call' and explains hop/gap-recovery behavior in plain terms, slightly extending schema semantics. This warrants a small bump to 4.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explains the decomposition/routing behavior. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making the tool's niche 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and explicit exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also instructs unsigned-in users to use ask_pipeworx instead, naming the alternative tool directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that results include full schemas with curated examples and are ready to call directly, 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 and usage guidance, then details. It's slightly long but every sentence adds value. Could be tightened slightly, but overall effective.

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

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

Given the tool's purpose and simple parameters, the description fully explains what it returns (top-N tools with schemas and examples) and how to use it. No output schema 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%, baseline is 3. Description adds value by listing example queries and stating aliases, though these are also in schema. Examples enhance 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 'Find tools by describing the data or task.' It lists many domains and distinguishes this discovery tool from sibling tools that perform specific tasks.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use versus alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds valuable context: it fans out across multiple sources, returns specific fields (e.g., up to 5 filings with URIs), and explains the patent soft-failure. 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 detailed and front-loaded with examples, but it slightly exceeds minimal conciseness with some redundancy (e.g., repeating that names not supported). Still efficient for the complexity.

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

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

Given the complexity (2 params, no output schema), the description is remarkably complete. It explains return values, limitations (patent API sunset, name restriction), and provides usage guidance. 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%, so baseline is 3. The description adds meaning by providing examples ('AAPL', '0000320193') and clarifying that names are not supported, which is beyond the schema's enum and description.

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

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

The description explicitly states the tool's purpose: providing a full cross-source profile of a US public company. It includes multiple user query examples and clearly differentiates from sibling tools like resolve_entity, stating to prefer this over chaining single-pack lookups.

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

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

The description provides clear when-to-use guidance (holistic view, e.g., 'tell me about X') and when-not-to-use (if only have a name, use resolve_entity first). It also notes the patent data limitation for context.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but does not significantly extend beyond annotations.

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

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

Two concise sentences: first states purpose, second provides usage guidance. No filler or redundant information.

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

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

For a simple delete operation with one parameter and annotations covering destructive and idempotent hints, the description and schema together provide complete context. No output schema 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?

With 100% schema coverage, the parameter 'key' is described in the schema. The description does not add additional semantic details 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 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes itself from siblings by mentioning 'pair with remember and recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Provides context but lacks explicit '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?

Description adds behavioral context beyond annotations: fetching page, extracting title/description/links, emitting standard markdown format. Annotations already provide safety hints (readOnly, idempotent), so description complements 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?

Three dense sentences with no filler. Front-loaded with purpose, followed by process and use cases. 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?

For a simple tool with 2 params and no output schema, the description fully explains input, process, output format, and usage scenarios. 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 value by specifying default (25) and max (50) for max_links, and clarifies the URL parameter usage. This goes beyond the schema's basic 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 generates an llms.txt file for any URL, with specific verbs like 'generate', 'fetches', 'extracts', 'emits'. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not explicitly exclude alternative tools, but context is clear and sufficient for an AI to decide when to invoke.

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 non-destructive. Description adds return field details (id, type, etc.) and default behavior (active only), but doesn't cover potential errors or limits.

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

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

Two concise sentences: first covers purpose and return fields, second provides usage guidance. Efficient and front-loaded.

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

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

Description explains return fields (compensating for lack of output schema) and usage context. Lacks details on pagination or errors, but sufficient for a simple list operation.

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% for the single parameter; description does not add extra information about parameters beyond what the schema already provides.

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

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

Description clearly states the verb 'list' and the resource 'subscriptions', specifies 'caller's active subscriptions' which distinguishes from sibling tools like subscribe and unsubscribe.

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

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing the return content (full text, discussion, guidance, related controls), source (official NIST OSCAL, public domain), and forgiving ID parsing. 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 front-loaded with purpose, followed by concise examples and format details. Every sentence is useful: it covers what the tool does, what it returns, acceptable IDs, and source, 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 one parameter, no output schema, and sibling tools, the description fully explains input flexibility and expected outputs. It mentions related controls and source, making it complete for an agent to use correctly.

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

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

Schema covers 100% of parameters with a description, but the tool description adds significant detail: accepted ID formats (e.g., AC-2, ac-2, AC-02, AC-2(1), 3.1.1), explicit examples, and behavior for enhancements and CUI IDs, which goes beyond the basic 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 looks up full text of NIST 800-53 or 800-171 controls by ID, including control statement, discussion, and related controls. It provides many specific examples, distinguishing it from sibling tools like nist_control_family and nist_control_search by focusing on individual control lookup.

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?

Examples like "what does NIST control AC-2 require" and forgiving ID formats implicitly guide usage. While it doesn't explicitly state when not to use or compare to alternatives, the context signals and sibling names suggest distinct use cases.

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 safe read-only, idempotent, non-destructive behavior. Description adds that it returns family title plus every control id+title including enhancements, but does not mention any edge cases like pagination or rate limits. Still strong.

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 somewhat lengthy but well-structured with examples and explicit usage guidance. Every sentence adds value, though could be slightly more 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 the simple input schema (1 parameter, no output schema) and comprehensive annotations, the description covers purpose, usage, and output format completely. 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% and already describes the parameter. Description adds examples and clarifies acceptable formats (codes or names), which provides marginal added value beyond the schema.

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

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

The description uses specific verb 'list' and resource 'NIST control family', and provides multiple example queries that clearly distinguish it from siblings like 'nist_control' and 'nist_control_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?

Explicitly says 'Use for' with example queries, and details valid inputs (family code or name) with examples. No ambiguity about when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds meaningful behavioral details beyond annotations: it notes 'All query tokens must match (case-insensitive AND).' and describes the return structure ({id, family, title, snippet}). No contradictions found.

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

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

The description is a single paragraph that front-loads the purpose and follows with usage rationale, query syntax, optional filters, return format, and examples. While concise, it could be slightly more structured (e.g., bullet points) but is not verbose.

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

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

Given 3 parameters with 100% schema coverage and no output schema, the description adequately covers matching behavior, optional filters, examples, and source information. An AI agent has sufficient context to invoke the tool correctly without missing critical 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining token matching behavior for the 'query' parameter and clarifying the 'family' parameter can be a code or name. It also provides concrete examples that demonstrate parameter usage.

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

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

The description clearly states 'Keyword search across NIST 800-53 security/privacy controls and NIST 800-171 CUI requirements by title and requirement text.' This specifies a concrete verb ('search'), resource (NIST controls/requirements), and scope (by title and requirement text). It distinguishes from sibling tools like nist_control and nist_control_family which serve different purposes.

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

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

The description explicitly says 'Use when the id is unknown' and provides example queries. This gives clear guidance on when to use this tool versus siblings that likely require an ID. While it doesn't explicitly exclude other scenarios, the context is sufficient for an AI 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 are minimally informative (all false), so the description carries the full burden. It discloses the two-phase workflow (filing returns a claim_token, passing it back later retrieves status), rate limiting (5 per identifier per day), and non-billing ('free; doesn't count against your tool-call quota'). A slight ambiguity remains about what happens when filing with an account, but overall behavior is well explained.

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

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

The description is long but every sentence adds meaningful context (scope, when-to-use, workflow, rate limits, billing). It is front-loaded with the purpose and remains organized, though it could be slightly tighter without losing 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 tool with no output schema, the description fully explains the return behavior: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed.' It also covers rate limits, billing, scope, and alternative handling, making it 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?

Input schema already provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description adds pragmatic semantic guidance beyond the schema, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and a usage example for claim_token, which enhances understanding of how to fill the parameters.

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

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

The description uses specific verbs and a clear resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also enumerates feedback types (bug, feature/data_gap, praise) and explicitly scopes it to Pipeworx tools, which distinguishes it from all sibling tools that serve research or subscription functions.

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 states exactly when to use the tool: '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 gives an exclusion, telling users to file elsewhere if the problematic tool is from a different MCP server, and instructs not to paste end-user prompts.

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

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

The description adds value beyond annotations by disclosing data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all consistent).

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

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

Three sentences, front-loaded with purpose, no redundant words. 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?

Despite having no output schema, the description adequately explains return types (top tools, packs, volume) and provides sufficient context for a low-complexity tool with comprehensive 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?

The schema fully covers the single parameter 'window' with enum and description. The description adds context: shorter windows for 'what's hot right now' vs longer for 'steady-state demand', enriching the schema's meaning.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on aggregated trending data.

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

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

Three explicit use cases are provided, covering discovery, confirmation, and alignment. However, no exclusions or alternatives are mentioned, leaving some ambiguity for an agent deciding between similar tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: scanning mechanics, similarity thresholds, partition filters, fill check against CLOB depth, and trade recommendations. 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 dense and well-structured with clear sectioning (SEMANTIC ANCHOR, PARTITION FILTER, etc.). However, it is verbose with detailed thresholds (3pp, 0.30 similarity) and exact response fields, which could be slightly condensed without losing clarity.

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

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

No output schema exists, so the description fully describes the response structure: opportunities array, partition_check in event mode, and fill check results. It covers all expected outcomes and edge cases (e.g., placeholder filtering, low similarity skipping), making the tool fully understandable.

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

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

Schema coverage is 100%, but the description enriches both parameters with detailed semantics (slug format, seed question example, behavior differences between modes). It explains cross-event similarity (0.30 Jaccard) and placeholder filtering, far exceeding schema bare-bones 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two operation modes (event and topic) and explicitly contrasts with sibling tools like polymarket_fill_risk, making its 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 provides explicit guidance on when to use each mode: event for a specific market, topic for cross-event scanning, and no args for trending scan. It warns against trading when realizable_edge_pp ≤ 0 and references polymarket_fill_risk for custom sizing, giving clear usage boundaries.

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

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

The description adds extensive behavioral context beyond annotations: it details response segments (by_segment), edge calculation (edge_pp_net after slippage, kelly_fraction), diagnostics for empty segments, 24h-move warning, and exclusion of Fed bets with rationale. No contradictions with annotations.

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

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

The description is front-loaded with purpose but becomes very dense with algorithm details (e.g., per-sport alpha, placeholder filters). While informative, it could be more concise; every sentence earns its place but overall length is high.

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 9 parameters and no output schema, the description is remarkably complete: it explains response structure (by_segment, diagnostics), tradeable-edge knobs, and all parameter intents. It also covers edge cases like Fed bets and why segments might be empty.

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 does not add per-parameter semantics beyond the schema; it explains parameters in context but not additional meaning for each parameter.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using specific verbs and resource. It distinguishes from siblings by focusing on Pipeworx discrepancy, though not explicitly naming alternatives.

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 frames the tool for 'what should I bet on today' and mentions agents can discover opportunities without paging hundreds of markets. It does not explicitly state when not to use or point to alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint, idempotentHint, etc., and the description adds context on data sources, trend computation, and limits (60-day TTL, daily closes). 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 informative and front-loaded with the key use case. It is relatively long but every sentence adds value. Could benefit from slightly more structured formatting.

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

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

Despite no output schema, the description comprehensively covers the response fields (tracked, expired, snapshot_dates) and limitations, making it self-contained.

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

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

Schema coverage is 100%, and the description adds meaningful defaults, ranges, and the concept of 'window family', plus explains the response structure which is absent from 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: it provides edge persistence and decay telemetry, answering when an edge is shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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

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

It specifies default and maximum values for days, the snapshot window family, and gives hints about when to use it (e.g., differentiating fresh vs old edges). However, it does not explicitly exclude alternative tools like polymarket_edges.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint = false) are consistent and non-contradictory. The description adds significant behavioral context: it details the walking of the order book ladder, the required parameter constraint, specific return fields, and explains forced directional risk, which 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 bolded mode names and outputs, front-loading the purpose. It is efficient, though slightly lengthy; each sentence adds value. Minor improvement could be trimming redundant phrasing.

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

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

Despite no output schema, the description thoroughly explains return fields for both modes, use cases, and risks (e.g., partial basket fills leading to directional exposure). It is nearly complete but could mention error handling or parameter validation.

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%, setting baseline at 3. The description adds value by explaining the semantics of size_usd in basket mode ('settlement notional — shares per leg'), clarifying side defaults (auto for basket), and giving examples. This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific outputs. It explicitly differentiates from sibling tools by saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

The description provides explicit guidance on when to use the tool: before acting on arbitrage signals or trades above $500. It explains why it's necessary (theoretical edge not capturable on thin books, partial fills cause directional risk) but does not explicitly state when not to use it, though it is implied for smaller trades.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters), edge cases (non-equivalent bet shapes, temporal misalignment), and details on matching logic. 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 (300+ words) but well-structured: purpose, modes, response details, safety fields. Every sentence adds value given the complexity (two modes, many edge cases). Slightly verbose but efficient for the content.

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

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

Given the complexity (cross-venue spread with matching logic, compatibility warnings, temporal alignment, skipped types) and lack of output schema, the description is complete: explains response structure, safety fields, and caveats. Agents can understand what the tool does and what to expect.

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

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

Schema coverage is 100% and description adds significant meaning: explains the two modes (topic with enum shortcuts, explicit tickers), provides examples, and notes that pre-mapped topics may not be tradeable. This goes beyond the schema's property descriptions.

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

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

The description clearly identifies the tool's purpose: compute cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts and explicit tickers) and explains what the response includes, differentiating it from siblings like polymarket_arbitrage or 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?

The description provides explicit usage context: when to use for cross-venue spreads, and when not to use (when compatibility_warning fires due to non-equivalent bet shapes or temporal misalignment). It warns that most pre-mapped topics return warnings, guiding agents to avoid assuming tradeability. However, it does not explicitly name alternative sibling tools.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds scoping (by identifier) and behavior of omitting key, providing extra context beyond annotations.

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

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

Succinct paragraph with front-loaded action, concrete examples, and companion tool guidance. 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?

Tool is simple (1 optional param) with solid annotations. No output schema but description hints return (value or list). Minor gap: doesn't specify return format, but acceptable.

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 parameter fully; description clarifies that omitting key lists all keys, adding semantic value and connecting to remember/forget pattern.

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

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

Clearly states it retrieves a value saved via remember or lists all keys when key is omitted. Distinguishes from siblings remember and forget by describing 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?

Describes use case: looking up stored context like ticker, address, notes. Mentions pairing with remember/forget for full workflow. Lacks explicit when-not-to-use but is adequate.

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 behavioral details: mark_read flag affects subsequent calls and polling is safe. No contradictions beyond the readOnlyHint issue noted separately.

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 paragraph, front-loaded with main purpose. Every sentence adds value: purpose, return fields, filters, mark_read behavior, polling suitability, and alternative endpoint. No 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?

No output schema, but description covers return fields adequately. Explains filtering parameters and side effect. Provides all needed info for a simple read tool with optional write side effect.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains 'type' with example ('sec_8k'), 'since' uses ISO timestamp, and 'mark_read' effect on next call. This goes 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?

Description clearly states it pulls fired events from subscription feed, specifies return fields (source, citation_uri, raw payload), and mentions filtering options. Distinct from sibling tools as no other tool focuses on subscription feed alerts.

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

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

Provides context that polling works fine and mentions an HTTP endpoint alternative for scripts, but does not explicitly guide when to use this tool versus other tools or when not to use it.

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

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

The description reveals multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback logic, soft-failure, and response structure. Annotations already declare read-only and idempotent, so the description adds substantial operational behavior.

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

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

Description is well-structured, front-loaded with purpose, and each sentence adds value. It is appropriately sized for the complexity, though slightly verbose in examples.

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

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

For a tool with no output schema, the description explains return structure (changes grouped by source, count, URIs) and covers parameter details, sources, and alternatives. Lacks mention of pagination or limits, but overall 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 covers all parameters, but the description adds concrete examples for 'since' and 'value' parameters, and clarifies the enum for 'type'. This enriches understanding beyond schema.

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

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

The description clearly states the tool returns a change feed for a company over a time window, and distinguishes from entity_profile for static profiles. The verb 'change feed' and resource 'company' are explicit.

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?

Usage guidelines are provided via explicit comparison to entity_profile (for static profile) and example queries. However, no explicit when-not-to-use scenarios are listed, but the context is sufficient.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), description adds storage scope ('scoped by your identifier'), persistence differences (authenticated vs anonymous), and 24-hour retention for anonymous sessions. 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?

Four sentences with no wasted words: purpose, usage guidance, storage behavior, and companion tools. Front-loaded with the core action, making it efficient.

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

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

For a simple write tool with no output schema, the description covers purpose, usage, storage details, and companion tools. Missing explicit return value mention, but 'pair with recall to retrieve later' implies minimal return.

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

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

Schema covers 100% of parameters with descriptions, but the description adds concrete key naming conventions (e.g., 'subject_property') and value types ('any text — findings, addresses, preferences'). This provides additional clarity 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?

Description clearly states 'Save data the agent will need to reuse later' (verb 'save', resource 'data') and distinguishes from siblings 'recall' and 'forget' explicitly. Examples like 'resolved ticker, target address' reinforce specific resource types.

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 context: 'Use when you discover something worth carrying forward' and pairs with recall/forget. Does not explicitly state when not to use, but the context is sufficient for decision-making.

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, idempotent, non-destructive), the description adds critical behavior: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit statement that unresolved identifiers are returned under `unresolved` rather than omitted, and cascading internal lookups. No contradictions with annotations.

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

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

The description is dense but well-structured: starts with user queries, then states the purpose and use-first directive, then details each supported type. While somewhat long, every sentence contributes meaningful context and the structure aids scanning. Could be slightly more concise but is not bloated.

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 entity types, multiple identifiers, external sources) and no output schema, the description thoroughly covers return expectations: identifiers labelled with source, unresolved items explicitly listed, and failure behavior. It also explains the replacement of multiple manual lookups, making it complete for an 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, but the description adds value by elaborating on the enum values ('company' vs 'drug') and giving concrete examples for the value parameter (ticker, CIK, name for company; brand/generic for drug). This goes beyond the schema's short 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 resolves names to canonical/official identifiers with specific examples ('ticker for...', 'CIK for...'), and explicitly differentiates from siblings by noting 'other tools require as input' and 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. The examples cover common query patterns, making the when-to-use clear, and the description distinguishes from profile-oriented tools like entity_profile or compare_entities.

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. Description adds that it probes each entity with ai_visibility_check, returns score/confidence/signal density, and handles optional API keys. 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?

Four sentences that are front-loaded with core functionality, followed by use case and return format. 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?

With no output schema, description fully explains return (ranked list with score/confidence/signal density). Covers all 4 parameters and their roles. Complete for moderate 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%, baseline 3. Description adds meaning: first entity is 'subject', models array includes defaults and Anthropic requirement, context disambiguates names. Exceeds 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?

Description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. Distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly states use case for competitive AI-marketing audits and provides example question. Lacks explicit when-not-to-use or alternatives, 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. Description adds behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. It also describes return structure clearly.

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

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

The description is a single dense paragraph but front-loaded with purpose. It contains useful details without being overly verbose. Slight improvement possible with bullet points, but effective as is.

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 composite nature of the tool, the description adequately covers purpose, usage, behavior, parameters, ecosystem scope, failure modes, and return values. No output schema exists, but the description compensates by listing return components.

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

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

Schema description coverage is 100% with both parameters documented. Description adds context that version defaults to latest published and scoped packages are accepted. This adds minor value beyond schema, so score 4.

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

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

The description clearly states the tool is a composite check for evaluating an npm package addition, combining data from deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by noting NPM-only scope and alternative tools for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clarifies when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Despite annotations already indicating safe and idempotent behavior, description adds rich details: returns top-N passages with offsets and scores, embedding model (BGE-base-en), cosine similarity, overlapping 500-char windows, 200K char cap with truncation flag. 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 and front-loaded with purpose, then usage, then technical details. Every sentence is informative, though slightly lengthy; could be tightened slightly without losing 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, description sufficiently explains return format (passages with offsets and scores). Covers behavior, constraints, and pairing with another tool. Complete for an agent to decide and invoke.

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

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

Schema coverage is 100%, but description adds value by explaining 'text' with examples (SEC 10-K body), 'query' as natural-language with examples, and 'limit' default 5. Goes 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?

Description clearly states 'semantic search INSIDE a fetched record' with specific verb and resource. Provides concrete examples (SEC 10-K, article) and distinguishes itself from siblings by emphasizing internal search and pairing with ask_pipeworx_grounded.

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: 'Use when the record is too big to cram into the prompt.' Also explains alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description adds significant behavioral context beyond annotations, such as the need for OAuth account, type-specific details, delivery channel behavior (e.g., webhook auto-disabled after 10 failures, SMS 10/day cap), and that the webhook secret is returned once. 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 well-structured: starts with purpose, then requirements, then types, then delivery options. It is dense but every sentence adds valuable information, with no redundancy or fluff.

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

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

Given the complexity (multiple subscription types, nested params, delivery options, constraints), the description covers all aspects comprehensively. It explains return value, authentication requirements, type-specific filters, delivery mechanisms, and limits. The sibling tools provide context for the subscription lifecycle.

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?

Although schema coverage is 100%, the description adds substantial meaning by providing concrete examples for each type's params (e.g., sec_8k with ticker and items) and explaining delivery constraints. This goes beyond the schema 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 that it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 specifies when to use (setting up proactive monitoring), requirements (Pipeworx OAuth account), and provides examples of supported types and delivery channels. It indirectly suggests when not to use (e.g., for viewing alerts use recent_alerts), but does not explicitly state 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 show it is read-only, open-world, idempotent, and non-destructive. The description adds that it returns dynamically drawn example questions from a live catalog, which is consistent and provides extra 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 front-loaded with the core purpose and well-structured, but slightly verbose with examples. Could be trimmed without losing clarity, but still effective.

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

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

Given the tool's simple purpose as an onboarding helper, the description covers everything: when to use, how to use, what it returns (category-bucketed examples). No output schema, but the description sufficiently explains the return value.

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 optional parameter with 100% schema coverage. The description adds a list of valid topics (finance, pharma, etc.) that are not in the schema as enums, and explains the effect of omitting 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?

The description clearly states it is the onboarding entry point for an agent wanting to know what it can ask. It lists example queries and specifies it returns category-bucketed example questions with tool calls. This distinguishes it from sibling tools like ask_pipeworx.

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

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

The description explicitly says to use this tool FIRST when you do not know what Pipeworx can do, and to learn meta-tools. It also explains how to use it: no arguments for full spread, or with topic for focus.

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 destructiveHint=false and idempotentHint=true; the description adds crucial behavioral details: ownership enforcement (only cancel own subscriptions), deactivation instead of deletion, and that historical events remain available via recent_alerts. No contradiction.

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

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

The description is two sentences, immediately states the main action, and provides necessary behavioral constraints without extraneous words.

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

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

For a simple tool with one parameter and no output schema, the description fully explains the action, side effects, and constraints, referencing related tool 'recent_alerts'. No missing information.

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

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

Schema description coverage is 100%, and the schema already explains the parameter ('Subscription id (uuid) returned by subscribe'). The tool description does not add further semantic detail beyond restating that the id identifies the subscription.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation vs deletion.

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

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

The description provides context about side effects (deactivation not deletion) and references 'recent_alerts' for historical events, but does not explicitly state when to use this tool over alternatives or when not to use it.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses critical behavioral nuances: the distinct meanings of 'could_not_verify' (check did not happen, carries verification_error) vs 'unsupported' (we looked, no source), and warns callers not to treat could_not_verify as evidence. This goes far 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?

Description is long but structured with example phrasings at the front, then a clear one-sentence definition, followed by routing details and return-value explanation. Every major section earns its place; the only minor redundancy is repeating 'grounded or structured' wording, but it remains organized and front-loaded.

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

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

No output schema exists, so the description compensates by fully explaining return values (verdicts list, actual value with citation, reasoning), error semantics (could_not_verify vs unsupported), and routing logic. Given the tool's complexity, this is a complete description with 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 covers both parameters at 100%, and description adds extra semantic value for tolerance_pct: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection' and default behavior ('capped at 5'). This practical guidance exceeds the baseline schema-only expectation.

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?

Specific verb+resource (verify factual claims against authoritative sources) with clear scope including natural-language phrasing examples. Distinguishes itself from siblings by explicitly stating it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), setting it apart from generic ask tools.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides detailed routing logic (company-financial claims via SEC EDGAR/XBRL, other claims via grounded pipeline). Does not explicitly name alternative sibling tools or list exclusions, but the routing guidance is strong enough to guide selection.

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