Data Tours

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint false. The description adds that Anthropic calls require user's API key and payment, and describes the return structure (per-model score, confidence, signals, raw_response + combined view). 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 concise (3-4 sentences) with no wasted words. It front-loads the core purpose, then details parameters and use cases. Every sentence serves a purpose.

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 moderate complexity (4 params, no output schema), the description explains the return values sufficiently (score, confidence, signals, raw_response, combined view). It could mention potential limitations like rate limits or response time, but overall it is complete enough for an agent to understand invocation.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the default model behavior for the 'models' parameter and the optional 'context' for disambiguation. It clarifies that '_apiKey' is only needed for Anthropic and is passed directly.

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 'probes LLMs for visibility' and scores from 0-100, specifying the verb (probe, score) and resource (business/brand/product/topic). It distinguishes from siblings by focusing on AI visibility measurement, unlike other tools like 'scan_competitor_ai_presence' which may be related but not directly compared.

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

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

Provides explicit guidance on default model (Workers AI free) and when to use Anthropic (BYO key). States use cases (AI-marketing audits, pre-launch checks, competitive monitoring). However, it does not mention when not to use or compare with sibling tools like 'scan_competitor_ai_presence', leaving some ambiguity.

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, idempotent, non-destructive behavior. The description adds valuable context: it routes to 5,529 tools across 1,455 sources, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. No contradictions with annotations, though it does not discuss failure modes or rate 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?

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and then efficiently expands with examples and escalation paths. It is structured with clear sections, though slightly verbose in enumerating domains and 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?

With no output schema, the description compensates by specifying the return type ('structured answer with stable pipeworx:// citation URIs'). It covers usage context, parameter semantics via examples, alternatives, and behavior, making it complete for a routing tool of this complexity.

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

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

Schema coverage is 100% with descriptions for the main 'question' parameter and aliases. The description adds example queries but does not explain parameter syntax or formatting beyond what the schema already provides. The baseline of 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly states the tool's function: it routes questions to the appropriate source among thousands and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives (ask_pipeworx_grounded, deep_research) and framing this as the default entry point.

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

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

The description is explicit about when to use this tool over web search and when to step up to alternatives. It provides concrete example queries and states that this is the default start point for most questions, with clear escalation paths to grounded or deep_research variants.

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, idempotent, open-world, non-destructive. The description adds context about the experimental nature: no active candidate as of 2026-07-26, current equivalence to ask_pipeworx, and that results are compared for merge decisions. This deepens understanding without contradicting annotations.

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

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

The description is concise and well-structured: definition, current state, usage directive, and clarification. Each sentence serves a purpose, with no filler or repetition.

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

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

The description covers purpose, experimental status, current equivalence, and evaluation role. Since there is no output schema, referencing 'same response shape' as ask_pipeworx is adequate for an agent familiar with the stable sibling. It is sufficiently complete for correct use, though it omits explicit output format 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?

The schema already covers all 6 parameters at 100% (all aliases for 'question'). The description mentions 'same arguments' but provides no additional semantics beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router handling 5,529 tools with identical arguments and response shape. It distinguishes itself from the stable sibling ask_pipeworx by its experimental status and live candidate evaluation.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies it is a full working router, not a fallback. The description implies when not to use it (when stability is preferred) but does not explicitly name an alternative other than ask_pipeworx.

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

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

Beyond the read-only/idempotent annotations, the description discloses the extraction constraint ('using ONLY what the tool result contains'), the exact return shape, the list of refusal reasons, and the extra LLM call cost. This is significant behavioral detail not present in the annotations.

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

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

The description is a single dense paragraph, front-loaded with the core purpose. Every sentence adds value—covering routing, extraction, return types, refusal reasons, use cases, and trade-offs—without verbose repetition.

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 fully explains the response format since there is no output schema, including success and refusal cases. It also covers usage context, cost implications, and enough routing detail to distinguish from ask_pipeworx, making it complete for a complex tool.

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

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

Schema description coverage is 100%, with all parameters being aliases of 'question' and clearly described as natural language. The description does not add any parameter-specific semantics, so it stays at the baseline for high schema coverage.

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

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

The description clearly states what the tool does: it's a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers using only the tool result, with a structured response including evidence. It distinguishes from sibling ask_pipeworx by noting the grounding behavior, extra LLM call cost, and appropriate use cases.

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

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

The description explicitly says when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists examples. It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups,' naming the alternative.

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

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

The description adds extensive behavioral context beyond annotations. It details the resolution process, safety mechanisms (low-confidence short-circuit, closed market detection, illiquid spread warning), resolver contract (confidence, match score, alternatives, suggestions), parent event extraction, news fallback fields, and resolution-rule risk. 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 long (multiple paragraphs) but front-loaded with the purpose. Every sentence adds value, but it could be more structured or concise to improve readability for an AI agent.

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

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

Given the tool's complexity (3 params, no output schema, rich internal logic), the description covers all needed aspects: what it does, how it resolves, response shapes, safety, risk rules, and examples. An agent has sufficient information to use and interpret results 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%, but the description enriches parameters: explains the three forms of 'market', clarifies 'depth' (quick vs thorough) and 'include_raw' (when to use true/false, impact on response size). Examples in schema add further clarity.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input forms (slug, URL, question text) and distinguishes from sibling tools by being a comprehensive research call that fans out to category-specific data.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives context but does not explicitly exclude alternative sibling tools like polymarket_edges or polymarket_arbitrage, which limits clarity on when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are already present and description adds significant detail: SEC EDGAR/XBRL data for companies with off-calendar fiscal year handling, FAERS/FDA data for drugs, sorted results, and 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?

Front-loaded with trigger phrases. Though lengthy, every sentence provides value about capabilities and constraints. Could tighten slightly but overall well-structured.

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

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

Given no output schema, description adequately covers return format (paired data + citation URIs), data sources, handling of fiscal years, and ordering. Comprehensive for a comparison tool with two entity types.

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

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

Schema coverage is 100% with both parameters described. Description adds context about enum values ('company' vs 'drug') and acceptable inputs (tickers/CIKs for company, drug names), plus explains sorting behavior, which supplements 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 specifies verb 'compare' and resource 'entities' with explicit side-by-side comparison of 2-5 companies or drugs. Clearly distinguishes from sibling tools by stating 'ALWAYS PREFER over sequential single-pack lookups' and noting it replaces 8-15 sequential 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?

Provides explicit when-to-use guidance ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and trigger phrases. Does not explicitly list alternatives or when-not-to-use, but the contrast with sequential lookups implies 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 readOnlyHint=true and destructiveHint=false, confirming safe read behavior. The description adds context about the metadata returned (fields/schema, themes, record count), enhancing transparency without contradicting annotations.

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

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

The description is a single, front-loaded sentence that conveys all necessary information without waste. Every part serves a purpose, earning a top score.

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

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

Given the tool's simplicity (one required parameter, no output schema, and rich annotations), the description provides sufficient context about what the tool does and when to use it. No additional information 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?

Schema description coverage is 100%, and the tool description reinforces the parameter's role by mentioning 'dataset_id' contextually. However, it does not add significant new meaning beyond the schema's description 'Dataset id from search_datasets'. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'metadata for one Tours Métropole Open Data dataset', listing specific metadata elements like fields/schema, themes, and record count. It also distinguishes from siblings by advising 'call before query to learn the column names', which differentiates it from query and search tools.

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

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

The description explicitly indicates when to use the tool ('call before query to learn the column names'), providing clear context. However, it does not explicitly state when not to use it or provide alternatives, though the purpose is well-defined.

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 far beyond the readOnly/openWorld/idempotent annotations, disclosing account and tier requirements, latency (15-60s, up to ~90s), parallel routing across 5,529 tools, gaps[] behavior (never invented), contradictions[] for standard/thorough, semantic excerpting, and citation resolvability. It adds rich behavioral context without contradicting the annotations.

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

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

The description is long but every sentence delivers a distinct fact—account requirements, alternatives, data sources, process, output format, iteration behavior, citation guarantees, and latency. It is front-loaded with the most critical information (account and alternative) and structured logically, making it appropriately sized for its 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?

With no output schema, the description fully compensates by explaining the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, and citation_uri. It also covers auth, tier gating, best-use cases, and failure modes (empty gaps for off-catalog topics), making it effectively complete for a complex tool.

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

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

Schema coverage is 100%, with the depth parameter already extensively described in the schema (quick=3, standard=5, thorough=8). The tool description reinforces the depth semantics but does not add significant new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from open-web search and ask_pipeworx. It is unambiguous about what the tool does and how it differs from its siblings.

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

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

Provides explicit usage boundaries: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states when deep_research is best: 'Best for broad/multi-part questions over structured data'. This is exemplary when-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing that each result includes full input schemas with curated examples and is ready to call directly, which helps the agent understand the output format and immediate usability.

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

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

The description is concise yet comprehensive. It front-loads the core purpose, lists domains, explains return value and usage context. Every sentence adds value without redundancy. Structure is logical and scannable.

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

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

With 6 parameters and no output schema, the description adequately explains what the tool returns (top-N tools with names, descriptions, schemas) and when to use it. It covers default/max limit (20/50) implicitly via schema but not explicitly in text, which is a minor gap. Overall, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'query' accepts natural language, providing examples (e.g., 'analyze housing market trends'), and noting aliases. This reinforces and enriches the schema definitions, earning a 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's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains it returns top-N relevant tools with schemas, making it obvious what the tool does. It distinguishes from siblings by advising to call this FIRST when many tools are available.

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It implies the alternative is to directly use a known tool, but does not explicitly state when not to use. Still, guidance is clear and actionable.

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

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

Annotations already mark the tool as readOnly, idempotent, openWorld, and non-destructive. The description adds context by detailing multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF) and noting that the patents component may soft-fail. It does not mention rate limits or latency, but the additional context is valuable.

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 example queries, then explains the tool's behavior and return fields. While somewhat verbose, it is well-organized and each sentence adds value. Minor redundancy, but overall 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?

Despite no output schema, the description enumerates all return fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and their sources. The agent can fully understand what the tool returns and how to interpret results. No critical information is missing.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description adds practical examples (ticker 'AAPL' or CIK '0000320193') and explicitly states that names are not supported, referencing resolve_entity for name resolution. This improves usability beyond the schema alone.

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

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

The description clearly states the tool returns 'full cross-source profile of a US public company in ONE parallel call,' lists specific output components, and explicitly distinguishes from chaining individual lookups. It also differentiates from the sibling 'resolve_entity' by noting name resolution is separate.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and provides a clear when-not-to-use condition: 'names not supported (use resolve_entity first if you only have a name).' This gives agents unambiguous guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds 'Delete' but doesn't clarify behavior for non-existent keys or side effects. With annotations, minimal extra info provided.

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

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

Two sentences, concise and front-loaded with purpose. No unnecessary words.

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

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

For a simple one-parameter destructive tool with good annotations, the description is largely complete. Could mention permanence of deletion but not critical.

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 description 'Memory key to delete'. Description doesn't add beyond schema, so baseline 3.

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

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

Clearly states 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'memory by key' are specific, distinguishing it from siblings like 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' and mentions pairing with remember and recall 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?

The description discloses key behaviors: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with this non-destructive, idempotent operation. The description adds value beyond annotations by detailing the extraction and output process.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by a brief explanation of the process and then concrete use cases. Every sentence adds value without redundancy or unnecessary detail.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description adequately covers the output format ('single text blob ready to drop at site-root/llms.txt') and the generation process. It could optionally mention error handling for invalid URLs, but that is not essential for completeness.

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

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

The input schema already covers both parameters with descriptions (100% coverage). The description adds contextual examples ('e.g. "https://example.com" or a specific landing page') and implies the use of max_links for limiting entries, which provides additional semantic meaning beyond the schema's bare descriptions.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the verb 'generate', the resource 'llms.txt file', and the context of AI crawlers. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning. The description also lists specific use cases, making the purpose unambiguous.

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

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

The description explicitly lists when to use the tool: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly state when not to use it or alternatives, but the use cases are clear and the context is sufficient for an AI to decide.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing the return fields and practical use cases, but the behavioral disclosure is already strong from annotations.

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

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

Two sentences, no wasted words. The first covers purpose and output, the second covers usage guidance. Properly front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and strong annotations, the description is complete. It explains what it does, what it returns, and when to use it.

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

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

The single parameter 'include_inactive' is fully described in the input schema (100% coverage). The description does not add additional meaning beyond the schema, so it meets the baseline.

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

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

The description clearly states the action 'List' and the resource 'the caller's active subscriptions', and it specifies the return fields. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading subscriptions.

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

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

The description explicitly advises when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and exclusion criteria.

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

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

With all annotation hints false, the description carries the full disclosure burden. It reveals the claim_token lifecycle (filing without an account returns one, pass it later to check status), rate limiting (5 per identifier per day), and that feedback is free and excluded from tool-call quota. It also warns against pasting end-user prompts, adding nuance beyond the schema.

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

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

The description is a single dense paragraph but each sentence earns its place: purpose, triggers, scope exclusion, content guidance, claim_token mechanism, team cadence, rate limit, and cost. It is somewhat lengthy but front-loaded and free of fluff.

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

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

Given the tool's complexity (two modes: filing vs. claim-based status check), the description fully explains the workflow, exclusions, and operational limits. The schema covers parameter formats; the description covers the human/team context (daily digests, roadmap impact) and the rate limit, making it adequate to use without external knowledge.

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

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

The input schema already describes all four parameters thoroughly (100% coverage), so the baseline is 3. The description adds usage-level semantics: it instructs to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which informs the `message` and `context` parameters. It also clarifies the `claim_token` round-trip pattern, though the schema already contains that.

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

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

The description opens with a clear purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly limits scope to Pipeworx-served tools, separating it from sibling research/query tools.

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

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

It provides explicit when-to-use triggers tied to the `type` enum (wrong/stale data → bug, missing tool → feature/data_gap, unexpectedly good → praise). It also names the alternative behavior: if the tool came from another MCP server, file it there instead, and it offers a heuristic for identifying Pipeworx tools ('tool names are the ones this connection lists').

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

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

Beyond annotations (readOnly, idempotent, not destructive), description discloses self-aggregating signal from CF analytics-engine, no PII, and caching behavior (5min-1h). No contradiction with annotations.

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

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

Single paragraph, front-loaded with output, bullet-style use cases, and methodology note. Every sentence adds value; no fluff.

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

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

For a simple read-only trending tool with one optional parameter, description covers return fields, caching, data source, and privacy. No output schema needed; complete for agent to use effectively.

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

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

Only parameter (window) is fully covered by schema (100% coverage). Description adds meaning: default is 24h, shorter windows surface what's hot, longer show steady-state demand, providing context beyond enum values.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', specifying the resource (Pipeworx trending data) and the verb (returns). It distinguishes from siblings like discover_tools by focusing on what agents are calling.

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 (discovering hot data sources, confirming canonical tool, aligning use case). Window usage guidance is given (shorter for hot, longer for steady-state). No 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 declare readOnlyHint, idempotentHint, openWorldHint. Description adds rich detail: walks child markets, uses semantic anchor with Jaccard similarity, partition filter for placeholders, fill check against CLOB depth. 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?

Description is lengthy but well-structured: first sentence summarizes, then mode-by-mode details, then fill check. Every sentence adds value, though some technical details could be slightly condensed. Front-loaded with core purpose.

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 provided, but description fully covers return values: opportunities[] and partition_check with fields. Also explains fill check behavior. Given the tool's complexity and three modes, the description is complete and leaves no obvious 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 substantial meaning beyond schema: explains what event slugs look like (e.g., 'fed-decision-may-2026'), how topic triggers cross-event scanning, and details internal behavior. This elevates beyond baseline 3.

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

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

Clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' Distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk and polymarket_edges by focusing on arbitrage detection.

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

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

Explicitly explains when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes when-not guidance: 'realizable_edge_pp ≤ 0 means... do not trade it' and references sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description goes far beyond by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), their calculations (e.g., lognormal barrier from FRED log-returns, GDELT article-volume ratio), caching behavior (1h KV keyed on all knobs), and response structure including diagnostics. There is 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 long but well-organized: it starts with purpose, then systematically explains the three segments, knobs, response structure, and caching. Every sentence adds value. While it could be slightly more concise, the complexity of the tool justifies the length, and the structure aids readability.

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

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

With no output schema, the description fully explains the response structure, including by_segment with its three categories, fed_candidates/fed_note, and _diagnostics. Each opportunity's fields are listed (edge_pp_net, kelly_fraction, etc.), and the caching behavior is documented. This is comprehensive given the tool's complexity.

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

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

Schema coverage is 100% with well-described parameters. The tool description does not add new parameter details beyond the schema, but it provides context for the tradeable-edge knobs and explains the min_partition_leg_kelly parameter indirectly through the description of partition_overround. Overall, the description adds marginal value over the schema parameter descriptions.

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

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

The description states the specific verb 'scan' and resource 'Polymarket markets' with the clear purpose of finding opportunities where Pipeworx data disagrees with the market price. It distinguishes from sibling tools by specifying the three response segments and the 'what should I bet on today' use case, making it clear this is for discovering edge opportunities rather than tracking or arbitrage.

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 the tool is 'built for "what should I bet on today"', providing a clear usage context. It explains that it avoids paging through hundreds of markets, but does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker. However, the detailed output structure and explanation of tradeable-edge knobs implicitly guide when to use.

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

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

The description adds significant behavioral context beyond annotations: it details the response structure (tracked, expired, snapshot_dates), explains limitations (60-day TTL, snapshot start date, decay from daily closes not intraday), and clarifies that data is derived from snapshots. This richness compensates for the absence of an output schema.

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

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

The description is relatively long but well-structured, with the main purpose front-loaded. The RESPONSE section is organized with clear bullet points. A few phrases could be trimmed, but overall it earns its length.

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

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

With no output schema, the description fully explains the response fields (tracked with edge_pp_net time-series, first_seen, trend, decay; expired with lifespan; snapshot_dates) and covers limitations. It provides a complete mental model for the agent.

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

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

Schema coverage is 100%, both parameters have clear descriptions. The description adds minimal extra meaning beyond the schema, such as clarifying 'window' as 'snapshot family' and default values. Given high schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the core question about edge duration and shrinkage. It effectively distinguishes this tool from siblings like 'polymarket_edges' by focusing on telemetry rather than raw edge data.

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

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

The description explains when to use the tool: to understand if an edge is fresh or aging, with a concrete example contrasting fresh vs. old wide edges. It does not explicitly list exclusions or alternatives, but the context is clear and sufficient for an agent to decide.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: walks the order-book ladder, returns slippage, verdict (clean/degraded/cannot_fill), and basket-mode risks (forced_directional_risk, thin_legs). 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?

Description is somewhat lengthy but well-structured: starts with main purpose, then details modes. Slightly repetitive in places (e.g., mentioning return fields twice), but overall efficient for the complexity. Could be slightly more concise, but still good.

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 description fully covers return values for both modes (e.g., top_of_book, vwap_fill_price, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, forced_directional_risk for basket). Addresses risks and edge cases comprehensively.

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

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

Schema coverage is 100%. Description adds significant meaning: explains different semantics of size_usd for single-market vs basket, default side logic in basket mode (auto from partition sum), and clarifies the return fields that correspond to parameters. Goes well 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 performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool instead.

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 context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable on thin books, partial basket fills convert arb to unhedged position). Also notes required parameter (market or event).

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

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

The description discloses critical behavioral traits beyond what annotations already provide: the two modes, auto-fetching logic, safety fields (compatibility_warning), temporal alignment checks, and skipped cross-type/subtype counters. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and the description adds rich context about when results are meaningless (e.g., temporal misalignment, non-equivalent bet shapes). No contradiction 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 comprehensive but somewhat lengthy. It is well-structured, front-loading key concepts (cross-venue spread, two modes, safety fields). Every sentence adds value, though the list of macro shortcuts could be slightly shortened. Overall efficient and clear.

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

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

Given no output schema, the description thoroughly explains the response structure: leg-by-leg prices, spread, compatibility_warning scenarios, temporal_alignment, and skipped counters. It also covers edge cases (non-equivalent bet shapes, semantically unrelated events). This is complete for a read-only, open-world tool with no output schema.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by listing the 10 pre-mapped topics, explaining that explicit tickers override the topic mapping, and providing examples. However, it does not add substantial new meaning beyond what is already in the parameter descriptions.

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

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

The description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The verb 'compute spread' and resource description are specific and 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?

It explicitly describes two usage modes (topic shortcuts vs explicit tickers) and provides detailed guidance on when to use each. It warns that most pre-mapped topics return a compatibility warning and that pre-mapped does not imply tradeable. This clearly helps the agent decide when and how to invoke the 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, and destructiveHint=false. The description adds context about ODSQL and query capabilities, but does not address rate limits, authentication, or error behavior.

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

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

The description is one sentence with a clear list of operations. It is efficient and front-loaded, with 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?

Despite 8 parameters and no output schema, the description does not explain what the tool returns (e.g., JSON format, metadata) or how parameters interact (e.g., query vs where override). This is insufficient for a complex query tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds overall context about query operations but no additional parameter-specific details, meeting the baseline.

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

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

The description clearly states the tool queries records from a specific open data dataset using ODSQL, and lists the main operations (filter, aggregate, sort, paginate). This distinguishes it from sibling tools like search_datasets which find datasets rather than query records.

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

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

No explicit guidance on when to use this tool vs alternatives. The description does not mention when not to use it or compare with sibling tools such as search_datasets or suggest_questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context about scoping and behavior (pairing with remember/forget) but does not contradict annotations. It adds value beyond the annotations by explaining the listing behavior.

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

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

The description is two sentences but packs significant information: purpose, dual behavior, usage context, scoping, and pairing with siblings. It is front-loaded with the action. However, it could be slightly more concise without losing meaning.

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

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

Given the simplicity of the tool (single optional parameter, no output schema), the description covers purpose, usage, scoping, and relationships. It is complete enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so the schema documents the parameter fully. The description adds value by explaining that omitting 'key' lists all keys, which is not explicit in the schema's description field. It clarifies the conditional behavior.

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 ('Retrieve', 'list') and clearly identifies the resource (values saved via remember). It distinguishes the dual behavior (retrieval vs listing) and implicitly differentiates from sibling tools 'remember' and 'forget'.

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

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

The description states when to use ('to look up context the agent stored earlier') and how to use (omit key to list all keys). It also mentions scope and pairing with remember/forget. However, explicit when-not-to-use or alternative sibling tools are not provided, missing some 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?

The description discloses key behavioral traits beyond annotations: the structure of returned events (source, citation_uri, payload), the effect of mark_read on subsequent calls, and the alternative endpoint. This adds value beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is a single compact paragraph with no wasted words. The main purpose is front-loaded, and each sentence contributes useful information. Slight improvement could be made by separating the alternative endpoint mention, but it remains 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 5 optional parameters, no output schema, and rich annotations, the description covers usage, filtering, and polling adequately. It could be more complete by briefly describing the return format beyond fields, but it is sufficient for an agent to use the tool 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?

Although the schema provides descriptions for all 5 parameters, the tool description adds deeper semantic context: e.g., explaining that mark_read flags events so future calls skip them, and that since is an ISO timestamp filter. 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 starts with a clear verb-resource pair ('Pull fired events from your subscription feed') and specifies the distinct functionality compared to siblings like list_subscriptions. It leaves no ambiguity about the tool's purpose.

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

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

The description provides usage context such as filter options by type and timestamp, mark_read behavior, and mentions polling suitability and an alternative HTTP endpoint. However, it does not explicitly state when not to use this tool or directly compare to siblings.

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

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

Discloses fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return structure (changes grouped by source, count, citation URIs). Annotations confirm read-only, idempotent, non-destructive, consistent with description.

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?

All sentences are informative without redundancy. Front-loaded with user-facing examples. 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 3 parameters, all required, no output schema, the description adequately explains return format and behavior. Covers source details, fallback, time window, and entity identification.

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 descriptions are present and description adds further context: type enum limited to 'company', since accepts ISO or relative with examples, value accepts ticker or CIK. Provides best-practice guidance for since parameter.

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

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

Description clearly defines tool as a change feed aggregator for companies over a time window, with examples of queries and specific data sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool 'entity_profile' for static profiles.

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

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

Explicitly states when to use this tool ('What's new with X') versus 'entity_profile' (static profile), and provides context for typical monitoring periods ('30d', '1m').

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds valuable context: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Two sentences, front-loaded with purpose, no wasted words. Structure is logical and easy to parse.

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 simple input (2 required params) and no output schema, the description fully covers behavioral and usage context, including lifetime and pairing with other tools.

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 clear descriptions. Description adds examples and context about key-value pairs, complementing schema but not repeating it.

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

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

The description clearly states the purpose ('Save data the agent will need to reuse later') and provides specific examples (resolved ticker, target address, user preference). It distinguishes from siblings like recall and forget.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and mentions alternative tools (recall, forget). Also clarifies session persistence behavior.

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 read-only/idempotent behavior, the description adds substantial behavioral context: it explains graceful degradation when GLEIF/OpenFIGI are unavailable, that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and that each call cascades through multiple endpoints. This goes well beyond the annotations and provides valuable transparency.

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

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

The description is dense but every sentence carries useful information, from usage examples to supported types and fallback behavior. However, the initial string of example queries could be trimmed without losing clarity, and the overall length is at the upper bound of what is comfortably 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 tool's complexity (multiple entity types, multiple identifiers, fallback handling) and the absence of an output schema, the description does an excellent job of covering behavior, return contents (including unresolved identifiers), and citations. It leaves very little ambiguity about 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%, so the baseline is 3. The description adds meaning by detailing what each entity type returns (e.g., for company: CIK, ticker, company_name, LEI, FIGI; for drug: RxCUI, ingredient, brand) and giving concrete examples like 'AAPL' and 'metformin.' This enriches the parameter semantics beyond the bare schema descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists specific resources (CIK, LEI, FIGI, RxCUI) and distinguishes itself from siblings by emphasizing it provides input for other tools. The examples of user queries make the intent 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 gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it 'replaces 2-3 manual lookups.' However, it does not explicitly state when not to use the tool (e.g., if you already have an ID), so it falls short of a full when-not/alternatives explanation.

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 confirms read-only, idempotent, non-destructive behavior matching annotations. Adds return format details (ranked list with score, confidence, signal density per entity) beyond the bare 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 dense sentences plus a parenthetical example. Front-loaded with verb+resource. No fluff, every sentence adds value.

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

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

With no output schema, description adequately explains return fields and ranking logic. Covers all parameters and use case. No gaps for an agent to misinterpret.

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

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

Schema coverage is 100%; description adds crucial context: entities must be 2-8, first is 'subject', and explains the role of each parameter clearly (e.g., models, _apiKey, context).

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

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

Explicitly states the tool compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks them, and surfaces leaders/laggards. Differentiates from sibling ai_visibility_check (single probe) and compare_entities (generic 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?

Clearly recommends use for competitive AI-marketing audits with a concrete question. Implies single-entity case should use ai_visibility_check. Does not explicitly mention alternatives like compare_entities, but the context is well-defined.

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

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

Annotations already provide safety hints; description adds degradation behavior, timing for bundlephobia, and sources_failed list, which are valuable beyond annotations.

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

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

Single paragraph with front-loaded purpose and details. Slightly long but well-structured and 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 provides return format and covers edge cases (scoped packages, defaults, partial failures, timing). Complete for this tool's complexity.

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

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

Schema coverage is 100% so baseline is 3; description adds context like scoped packages accepted, version default, and return structure details, justifying a 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?

Clearly states it is a composite check for npm packages combining deps.dev and bundlephobia. Distinguishes from sibling tools by specifying the exact set of checks and ecosystem.

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 whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also notes NPM-only in v1 and partial failure handling.

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 the tool as read-only, idempotent, and non-destructive. Description adds return content details, which is useful but not critical 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 with no filler, front-loaded with action. Every word adds value.

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

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

Given the tool's simplicity and comprehensive schema/annotations, the description provides enough context: what it does, what it returns, and how to use results. 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 covers 100% of parameters with descriptions. Description does not add extra semantics beyond mentioning keywords; it is adequate but not enhanced.

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 searches Tours Métropole Open Data for datasets by keyword, specifying domains and mentioning it returns dataset_ids, titles, themes, and record counts. Distinguishes from sibling dataset_info tool.

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 returned dataset_ids can be passed to query/dataset_info, providing a clear usage pattern. Does not explicitly state when not to use but implies alternatives.

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

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

Discloses embedding model (BGE-base-en), algorithm (cosine similarity, 500-char windows), and limits (200K chars truncation). This adds value beyond readOnlyHint/idempotentHint 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 includes a somewhat lengthy technical explanation. Every sentence is useful, though it 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 no output schema, the description adequately explains return values (passages, offsets, scores) and algorithm. Pairs with sibling tool and covers truncation behavior.

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

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

Schema coverage is 100%, and parameter descriptions already cover semantics. The description provides example queries for 'query' but does not add significant new information 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 'Semantic search INSIDE a fetched record' with specific verb (search) and resource (record). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and provides direct guidance on when to use and alternative (ask_pipeworx_grounded).

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

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

The description discloses important behavioral traits: requirements, type-specific filters, delivery channels with constraints (sms cap 10/day, email validation, webhook auto-disable). However, it does not address the idempotentHint=true annotation; a creation tool typically is not idempotent, and this discrepancy reduces transparency.

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

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

The description is front-loaded with the core action and return value, then follows a logical order: requirements, types, delivery channels. Every sentence adds value, and there is no redundancy despite the wealth of detail.

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

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

Given the tool's complexity (3 parameters with nested objects, 5 subscription types, multiple delivery channels including webhook details), the description covers all essential aspects: constraints, examples, rate limits, and authentication needs. No output schema exists, but the description mentions 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?

The description adds significant meaning beyond the input schema: it provides concrete examples for each subscription type, details on delivery channel options (including webhook signing and auto-disable), and explains the always-on feed. Schema coverage is 100%, and the description enriches 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 uses a specific verb 'Create' and resource 'proactive monitoring subscription', clearly stating it returns the new subscription id. It distinguishes itself from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts' by focusing on creation and proactive monitoring.

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 clearly states when to use the tool (proactive monitoring) and gives explicit requirements (Pipeworx OAuth account; anonymous/BYO cannot persist). It does not explicitly mention alternatives or when not to use, but the context is clear enough for an agent to choose appropriately.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds beyond this by detailing the output structure (categories and example questions) and the effect of the topic parameter.

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

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

The description is fairly long but well-structured: starts with sample queries, then states purpose and output, then usage guidance. Every sentence adds value, though it 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?

Despite lacking an output schema, the description fully explains what the tool returns and how to use it. It covers purpose, parameters, output, and usage context, making it complete for an onboarding tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by listing possible topic values and explaining that omitting it gives a full spread, enhancing the schema's description.

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

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

The description clearly states the tool's purpose: to return category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings by specifying its use in initial exploration.

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

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

The description explicitly advises using this tool first when unsure of Pipeworx's capabilities, and provides guidance on passing a topic for focus. It lacks explicit when-not scenarios but this is acceptable given the clear context.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events. No contradictions with annotations.

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

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

Two concise sentences with no wasted words. The first sentence states the purpose, and the second explains key behaviors.

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 effect (deactivation, ownership, historical data) and provides sufficient context for correct usage.

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

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

The input schema has full coverage (100%) for the single parameter 'id', which is clearly described as a subscription UUID from subscribe. The description does not add further detail, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription', with sufficient specificity. It distinguishes itself from the sibling 'subscribe' tool by the action of cancellation.

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

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

The description explains ownership enforcement and the deactivation behavior, which helps the agent decide when to use it. However, it does not explicitly state when not to use it or mention alternatives for related actions like listing subscriptions.

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 substantial behavioral context beyond the annotations: it explains the two processing pipelines (SEC EDGAR + XBRL vs. grounded), defines all verdict types, and critically distinguishes 'could_not_verify' (check failed) from 'unsupported' (no source found). It also warns callers not to treat 'could_not_verify' as evidence, which is essential operational guidance.

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 dense; every sentence adds value, from trigger examples to pipeline details and caller warnings. It is front-loaded with usage phrases and structured logically, though slightly verbose for a tool description.

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

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

With no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning) and error semantics. It also covers the two distinct processing paths and the important difference between 'could_not_verify' and 'unsupported', making it complete for a complex tool.

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

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

The input schema already provides thorough descriptions for both 'claim' and 'tolerance_pct', including examples and the hallucination-detection use case, so schema coverage is 100%. The description adds little parameter-level meaning beyond what the schema already states, so it stays at the baseline of 3.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with specific trigger phrases like "fact check" and "verify the claim that…". It also distinguishes itself from sibling tools by highlighting that it replaces 4–6 sequential calls, making its integrated purpose clear.

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

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

It explicitly states "Use whenever the agent needs to check whether something a user said is factually correct," providing clear when-to-use context. It also describes the routing logic for company-financial claims vs. other claims, though it does not name specific alternatives or exclusions.

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