Openfoodfacts

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details: default model is free, Anthropic requires BYO key, return structure includes per-model {score, confidence, signals, raw_response}. 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, no wasted words. First sentence states the core action and output; second provides key details (default model, key requirement, use cases). Front-loaded with important information.

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

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

No output schema, but description explains return format per model and combined view. Covers most aspects: different models, optional key, use cases. Could mention what 'signals' entails, but overall sufficient 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 description coverage is 100%. The description adds valuable context beyond the schema: explains that 'workers-ai' is the free default, clarifies that '_apiKey' is only needed for Anthropic and is passed through, and that 'context' aids disambiguation. This enhances parameter understanding.

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

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

The description clearly states the verb 'probe' and 'score', the resource 'visibility across LLMs', and the output 'score (0-100) per model'. It distinguishes itself from sibling tools that retrieve structured entity data (e.g., brand, product) by focusing on LLM knowledge.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains when to use the optional _apiKey (for Anthropic). Does not state explicit exclusions or alternatives but provides sufficient 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 readOnly, openWorld, idempotent, non-destructive. The description adds that it routes to 5008 tools across 1318 sources, returns structured answers with pipeworx:// citation URIs, and works on all tiers. No contradictions.

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

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

Description is long but well-structured: preference statement, use cases, sibling comparisons, examples. Front-loaded with key guidance. Every sentence provides value, though slightly verbose.

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

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

For a tool with no output schema and extremely broad scope, the description is remarkably complete. Covers when to use, what to expect (citations, structured answers), limitations, and examples. 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 has 100% coverage documenting question parameter and its aliases. Description adds natural language usage examples and context for the question parameter, going beyond schema definitions.

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

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

The description clearly states the tool routes factual questions to authoritative structured data sources, listing specific domains (SEC filings, FDA data, etc.) and contrasting with web search. The verb 'ask' and resource 'Pipeworx' are well-defined.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides extensive when-to-use guidance with examples. Compares with sibling tools ask_pipeworx_grounded and deep_research, specifying when to step up.

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 significant behavioral context: it is a full working router, experimental edge, with source-preference ranking behavior, and no fallback. This enriches transparency beyond annotations.

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

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

The description is moderately long but efficiently packs purpose, key differences, and usage guidance. It is front-loaded with the core purpose. Minor room for trimming, 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 the tool's complexity (beta router with 5,011 tools), the description covers purpose, usage, behavioral traits, and distinguishes from the stable sibling. No output schema exists, but the return values are implied to be same as ask_pipeworx. Complete enough for the context.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question'. The description does not add any additional meaning beyond what the schema provides, 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 states it is a beta version of ask_pipeworx, a universal router with the same tools and arguments, and highlights the source-preference ranking feature. It distinguishes itself from the sibling 'ask_pipeworx' (stable) and 'ask_pipeworx_grounded' (likely different), earning a top score.

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 it 'exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. However, it does not provide explicit when-not-to-use scenarios or alternatives beyond the sibling names, so it falls short of a 5.

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

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

Discloses that it 'picks the right tool, fills arguments, fetches data, then extracts answer using ONLY the tool result' and returns structured responses with explicit refusal reasons. Aligns with annotations (readOnlyHint, idempotentHint) and adds valuable context about the refusal mechanism and cost.

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 efficient paragraph, front-loaded with purpose and behavioral highlights. Every sentence serves a clear function (purpose, mechanism, return format, usage guidelines, trade-off). No 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?

Despite lacking an output schema, the description thoroughly explains the return structure (fields like answer, evidence, confidence, refusal_reason) and possible refusal conditions. This compensates fully for the missing schema, making the tool behavior predictable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that all aliases (q, text, input, query, prompt) map to 'question' and clarifying that the parameter expects 'natural language'. This aids correct parameter usage beyond the schema.

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

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

The description clearly identifies a specific verb ('ask') and resource ('Pipeworx Grounded'), with a distinct purpose: hallucination-resistant answer extraction for high-stakes reads. It distinguishes itself from sibling tools like 'ask_pipeworx' by emphasizing grounded, evidence-only responses.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, etc.). Also provides an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off of an extra LLM call.

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

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

The description goes far beyond annotations, detailing resolution behavior, fan-out patterns, response shapes, resolver contract, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market detection, wide-spread warnings), and cancellation rule risk. All behavioral traits are disclosed transparently, and 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with a clear purpose statement. It is verbose but every sentence adds value, making it informative rather than wasteful. Minor improvement could be condensing some examples, but overall it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description provides comprehensive coverage of all expected behaviors, edge cases, and response shapes. It explains resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution-rule risk, ensuring an agent can fully understand and 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?

Schema coverage is 100% with each parameter having a description. The description adds context about fan-out examples and response shapes but does not significantly enhance parameter semantics beyond the schema. For example, depth and include_raw are adequately described in the schema, so the description adds marginal value.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the accepted inputs (slug, URL, question text) and provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This differentiates it from sibling tools like polymarket_edges or validate_claim.

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

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

The description explicitly tells when to use the tool: for researching specific bets and assessing edge. It gives clear usage scenarios and contrasts with alternatives by focusing on a single bet versus tracking or arbitrage. While it doesn't list sibling names, the context and use-case framing provide sufficient 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, open-world, and non-destructive behavior. The description adds no additional behavioral context (e.g., rate limits, auth requirements, or side effects). It does not contradict 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 extremely short (3 words), but this sacrifices completeness. It is front-loaded but inadequate given the lack of parameter documentation. Every sentence should earn its place; here it is too terse.

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 good annotations and an output schema, the description omits essential context about pagination parameters and usage of the required 'brand' field. It is too minimal for effective agent selection.

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

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

With 0% schema description coverage, the description must compensate. It clarifies that the 'brand' parameter filters products, but provides no explanation for 'page' or 'page_size' parameters (e.g., pagination behavior, defaults). This falls short.

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 'Products by brand.' indicates the tool returns products filtered by brand. It is clear about the resource (products) and filter (brand), but does not differentiate from sibling tools like 'category' or 'product', which also return product lists with different filters.

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 usage guidance is provided. The description does not specify when to use this tool versus alternatives (e.g., 'product' or 'category'), nor when not to use it. No prerequisites or context are mentioned.

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 no behavioral information beyond the annotations. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description does not disclose pagination behavior or any other traits.

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 exceedingly short at two words. For a simple tool with few parameters, this is concise and front-loaded, though it could benefit from slightly more detail without losing brevity.

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

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

Given the tool has three parameters and an output schema, the description is incomplete. It does not explain pagination behavior or the structure of the response. Despite annotations covering safety, the description fails to provide sufficient usage context.

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

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

With 0% schema description coverage, the description must compensate. It only hints that 'category' is the filter, but provides no explanation for 'page' or 'page_size' parameters. The input schema has examples but the description does not clarify their meaning.

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

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

The description 'Products by category' clearly states the tool retrieves products filtered by a category. It uses a specific verb and resource, but does not distinguish it from siblings like 'brand' or 'country' which may also list products.

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 no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest sibling tools for different filtering needs.

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 rich context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted output, and citation URIs. This goes beyond annotations.

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

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

The description is slightly long but every sentence adds value. It is front-loaded with common user query patterns and structured logically. Could be trimmed slightly but remains 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 adequately explains return values (paired data + citation URIs). It covers data sources and sorting. Missing error handling details, but overall sufficient for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning beyond the enum values and array constraints. It explains what data each type pulls (10-K financials vs. FAERS counts) and clarifies that values are tickers/CIKs for companies and drug names for drugs.

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 does side-by-side comparison of 2-5 companies or drugs in one call, with specific verb phrases like 'Compare X and Y'. It distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'.

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

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

The description provides explicit guidance to prefer this tool over sequential lookups for comparisons, and gives example queries. It does not list alternative sibling tools by name, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds minimal behavioral context; it does not mention pagination behavior or error handling, but does not contradict 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 concise sentence with no wasted words. However, it is borderline under-specified, lacking details that could be added without significant verbosity.

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

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

Despite having an output schema and clear annotations, the description is too brief to fully contextualize the tool. It does not clarify how 'country' differs from sibling tools like 'product' or 'category', leaving potential confusion 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 description coverage is 0%, meaning no parameter descriptions in the schema. The description does not provide any additional meaning for parameters like 'page', 'country', or 'page_size'. The agent must infer from names 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 states that the tool returns products associated with a country, but it does not specify a verb or distinguish from sibling tools like 'product' or 'brand'. The purpose is clear but lacks specificity and differentiation.

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

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

No guidance on when to use this tool versus alternatives like 'product' or 'search'. There is no mention of prerequisites, filtering, or context where this tool is preferred.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich detail: returns findings packet with evidence, confidence, source, citations, gaps array, contradictions, semantic excerpting, hop field, and expected response times (15-90s). No contradictions with annotations.

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

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

The description is long but well-structured, front-loading essential info (account requirement, core functionality, alternatives) before detailing depth levels and output format. Every sentence adds necessary context for a complex tool; conciseness is reasonable given the content volume.

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 (no output schema, 2 params, many sources and tools), the description thoroughly covers output format, iteration behavior, depth details, account tiers, time expectations, and handling of missing topics. It compensates fully for the lack of 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 baseline is 3. The description adds value by explaining each depth value (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+iterative+contradictions) and encourages broad questions for the question parameter, which goes beyond schema descriptions.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources' and distinguishes it from siblings like ask_pipeworx by specifying its use for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups or breaking news.

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

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

The description explicitly states when to use this tool (broad/multi-part questions over structured data) and when not to (single lookups -> ask_pipeworx, breaking news -> ask_pipeworx). It also explains account requirements and depth choices, providing direct alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral details: returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. No contradictions.

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

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

The description is concise (4-5 sentences), front-loaded with the core purpose, and every sentence adds value. 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?

Given the tool's meta-discover nature and high annotation/schema coverage, the description is complete. It explains what the tool returns (names, descriptions, full schemas) and addresses the key behavior needed for an agent to use it first.

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

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

Schema coverage is 100%, but the description adds value by explaining that 'query' is a natural language description, listing aliases, and specifying limit default/max. This enhances understanding beyond schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of tasks and distinguishes itself from sibling tools by being a meta-discovery tool for browsing available 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives clear context but does not explicitly state when not to use it, though the guidance is strong enough.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral details: fans out across multiple sources, patents may soft-fail due to sunset, specific fields returned. No contradictions.

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

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

The description is a single paragraph that is front-loaded with example queries. While slightly long, each sentence adds value and it is well-structured. Could be a bit more concise but overall 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?

Despite no output schema, the description thoroughly explains returned data (cik, company_name, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail, names unsupported). For a complex multi-source tool, this is very complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining that type is limited to 'company' and value can be ticker or zero-padded CIK, and explicitly states names are not supported. This adds value beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with specific examples like 'Tell me about X' and lists data sources and outputs. It distinguishes from sibling tools by noting it should be preferred over chaining single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides clear constraints: names not supported, use resolve_entity first. This gives excellent when-to-use and when-not 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. The description adds minimal behavioral context beyond 'delete' (e.g., it says 'previously stored'), but no additional traits like irreversibility or effects on other operations. It is adequate but not rich.

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 the action, and no wasted words. Every sentence provides value: purpose and usage guidance. Extremely 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?

For a simple deletion tool with one parameter and annotations, the description covers purpose, use cases, and sibling tools. It lacks details about return values (success/failure), but the context is sufficient for an agent to understand the tool's role.

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

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

Schema coverage is 100%, and the description only mentions the parameter 'key' without adding new semantics beyond what the schema already provides. 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 explicitly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall' by being the deletion counterpart, providing clear differentiation.

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

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

The description gives clear scenarios for use: when context is stale, task is done, or to clear sensitive data. It pairs with related tools but does not explicitly exclude alternatives, making it slightly less than perfect.

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=true and non-destructive, and the description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' No contradictions with annotations.

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

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

The description is a single paragraph with multiple sentences, but it is well-structured and conveys all necessary information clearly. It could be slightly more concise, but it is not overly verbose.

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

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

Given the tool's complexity (2 parameters, no output schema), the description covers the output format ('single text blob'), behavior, and use cases. It is complete enough for an agent to understand and invoke 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?

Schema description coverage is 100%, and the description adds extra context beyond the schema, such as example URL format and default/max for max_links. This adds meaningful guidance for parameter usage.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file for any URL' and specifies the output format and purpose. It distinguishes from siblings by focusing on a specific file generation task, which is distinct from the listed sibling tools.

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

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

The description provides explicit use cases: getting a client's site indexed by AI, drafting llms.txt for own project, or auditing competitor AI crawler view. While it doesn't state when not to use or list alternatives, it gives clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by detailing the returned fields and implying default behavior (active subscriptions). 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: first concisely states purpose and outputs, second provides usage context. No unnecessary words. Front-loaded with key information.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers what it does, what it returns, and when to use it. Complete given the 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 covers the single parameter with a description. The tool description does not add new meaning beyond the schema; it simply states the default behavior. 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 'List the caller's active subscriptions' and enumerates return fields. It distinctively positions the tool among siblings like 'subscribe' and 'unsubscribe' as a read-only review 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Tells when to use, though no explicit exclusion of alternatives. Clear enough for effective selection.

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

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

The description discloses important behavioral traits beyond annotations: it is free, rate-limited (5 per identifier per day), and that feedback is read daily and affects roadmap. Annotations indicate it is not read-only, not idempotent, etc., but description adds context about rate limiting and impact.

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 (under 100 words) and well-structured. It front-loads the main purpose, then provides usage guidelines, then additional details. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description thoroughly covers what the tool does, when to use, rate limits, and behavioral notes. It provides sufficient information for the agent to use it correctly, including a mention of how the feedback is processed (daily digests). The lack of output schema is not an issue since the tool is fire-and-forget.

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 each parameter. The description adds extra context for 'type' enum (e.g., mapping to bug, feature, etc.), for 'context' (optional structured info), and for 'message' (be specific, 1-2 sentences, 2000 chars max). This goes beyond the schema, justifying a score above 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?

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools, none of which serve a feedback function.

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 specifies when to use the tool (e.g., 'when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog'), and provides a clear alternative (not pasting user prompts). It also mentions rate limits and that it doesn't count against quota, helping the agent decide when to invoke.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds valuable context: derived from analytics engine, no PII, caching duration. No contradiction.

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

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

Three well-organized sentences, front-loaded with main output. Every sentence adds value; no superfluous text.

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

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

Despite no output schema, description clearly specifies return fields (top tools, top packs, total call volume). Caching and data source are provided. Sufficient for a simple read-only tool with one optional parameter.

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?

Single parameter 'window' is well-documented in the schema with enum and description. Tool description reiterates window options but does not add meaningful new semantics beyond schema (which already covers 100%).

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 what the tool does: returns top tools, top packs, and total call volume for a given time window. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on aggregated usage trends.

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

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

Explicitly lists three use cases (hot data discovery, canonical tool confirmation, alignment check) and mentions caching and source. Lacks explicit 'when not to use' but provides strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds extensive behavioral details: monotonicity violations, partition checks, similarity filtering, placeholder filtering, and fill check. It discloses conditions that lead to null signals and explains when trades should not be executed, enhancing transparency beyond annotations.

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

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

The description is thorough but somewhat lengthy; however, it is well-structured with clear sections: purpose, modes, semantic anchor, partition filter, fill check. The first sentence immediately states the main action, and each subsequent part adds necessary detail. A 4 is appropriate due to minor verbosity, but it remains effective.

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

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

Despite no output schema, the description fully explains the response structure (opportunities[], partition_check details) and handles edge cases like placeholder filtering and fill check. It also references sibling tools for complementary use. For a tool with 2 optional parameters and no required fields, the description is exceptionally complete.

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

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

Schema coverage is 100% with both parameters described. The description adds significant value by explaining the behavior of each mode in depth, including examples of slugs and seed questions, and how the parameters affect scanning scope. It goes well beyond the schema descriptions, justifying a score above baseline.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses specific verbs and resources, and clearly distinguishes from sibling tools like `polymarket_edges` and `polymarket_fill_risk` 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?

The description provides clear guidance on when to use each parameter: NO args for trending scan, `event` for specific market, `topic` for cross-event scanning. It explains the context for each mode, recommends `event` for known events, and refers to `polymarket_fill_risk` for custom sizing, effectively covering alternatives and exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral details: caching at KV level keyed on all knobs, segmentation into three response categories, diagnostics for empty segments, and edge calculation methodology. No contradictions.

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

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

The description is very long and detailed, which might overwhelm agents. While structured with segments and bullets, it could be more concise. Not all information earns its place; some details (e.g., exact model formulas) could be abbreviated.

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

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

Despite having no output schema, the description fully explains the return structure (by_segment, fed_candidates, _diagnostics) and caching behavior. It covers edge calculation, filter knobs, and why segments might be empty. Complete for the tool's complexity.

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

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

Schema coverage is 100% with all 9 parameters described. The description adds substantial meaning beyond the schema, such as explaining slippage_pp, min_kelly application, and tradeable-edge filters. It provides practical guidance for parameter tuning.

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

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

The description clearly states the tool scans top Polymarket markets and finds opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven edges.

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

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

The description provides clear usage context ('discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs. It does not explicitly state when not to use it, but the sibling tool list gives context for alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: response structure (tracked, expired, snapshot_dates), limits (60-day TTL, not intraday), and computation method (daily closes). 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 detailed but well-structured, front-loading the core purpose. While it could be slightly more concise, every sentence contributes useful information.

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

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

Given the simple parameters, comprehensive annotations, and no output schema, the description fully explains the return values, constraints, and interpretation, making it complete for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds context (default values, clamping) and clarifies the relationship between parameters and snapshot families, providing extra value beyond the schema.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay using daily snapshots. It answers the specific question about edge age and distinguishes the tool from siblings like polymarket_edges by focusing on historical context.

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

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

The description provides context on when to use the tool (e.g., differentiating a fresh wide edge from an old one) but does not explicitly list when not to use it or directly compare with alternatives.

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

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

Annotations indicate read-only, nondestructive, idempotent. Description adds behavioral details: walks order-book ladder, returns slippage, verdicts, and warns about forced directional risk in baskets. No contradiction with annotations. Provides context beyond safety profile.

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

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

Description is long but well-structured with sections: overall purpose, requirements, single-market mode, basket mode, usage warning. Every sentence adds necessary detail for a complex tool. Slightly verbose but justified.

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 tool complexity (two modes, many return fields, risk warnings), description is fairly complete. Explains both modes thoroughly, lists return fields, and provides usage guidance. No output schema, so description carries burden adequately.

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

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

Schema descriptions cover all 4 parameters (100% coverage). Description adds value by clarifying mode-specific defaults (e.g., side auto in basket) and interpreting size_usd for baskets. Schema provides basics; description adds nuance.

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 performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, lists specific return fields, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use the tool: before acting on certain signals or trades above ~$500. Explains why (theoretical overround not capturable, partial fills cause directional risk). Provides clear context and exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: two modes, response structure with leg-by-leg prices and top spreads, safety fields including compatibility_warning, temporal_alignment, and skipped_cross counters. 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 every sentence adds value. It is front-loaded with core purpose and logically structured. Could be slightly more concise but appropriate for complexity.

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

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

Given the complexity (two venues, two modes, safety fields, no output schema), the description is virtually complete—covering response structure, safety field meanings, and warnings about false positives. There are no gaps.

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

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

Schema coverage is 100% and description adds meaning beyond schema by explaining the relationship between topic and explicit tickers, providing examples, and clarifying that explicit tickers override the topic-mapped side.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, and names two modes (topic shortcuts and explicit tickers). It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit when-to-use context, explaining that the delta is a real signal only when bet shapes are equivalent, and warns that pre-mapped topics often return compatibility warnings. It does not explicitly name alternatives but the context is clear.

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

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

Annotations provide strong safety signals (readOnly, idempotent, non-destructive), but the description adds no additional behavioral context (e.g., whether it returns full product details, pricing, or availability). It does not contradict 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?

Extremely concise (5 words), efficient, and front-loaded. Could be improved by adding a brief summary of output, but no wasted text.

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

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

Despite having an output schema, the description lacks details on what the tool returns (e.g., product name, category, price). For a simple barcode lookup, the agent may need to infer functionality from examples alone.

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 0%, and the description only mentions 'by barcode', which adds little beyond the property name. Examples in the schema help but are not referenced in the description, leaving parameter semantics under-explained.

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 'Product by barcode.' clearly states the action (retrieve product info) and the identifying resource (barcode), distinguishing it from sibling tools like 'brand' or 'search'.

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

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

No guidance on when to use this tool versus alternatives (e.g., 'brand', 'category', 'search'). The description lacks context for selecting among similar lookup tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds context about scoping and example use cases, but goes beyond annotations by explaining the tool's purpose and data scoping.

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 covering core functionality, usage, scoping, and pairing. Front-loaded with main action. 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 read tool with one optional parameter and annotations providing safety signals, the description fully covers purpose, usage, scoping, and relationships to siblings. No gaps.

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

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

Schema coverage is 100% and already describes the 'key' parameter as 'Memory key to retrieve (omit to list all keys)'. Description repeats this but adds examples of key values, which is marginally helpful but not substantial.

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

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

Description uses specific verb 'Retrieve' and resource 'value saved via remember', and distinguishes from siblings by naming 'remember' and 'forget'. Clearly states both retrieval and listing modes.

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: 'look up context... without re-deriving it from scratch'. Also explains scoping and pairs with remember/forget, giving clear alternatives.

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

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

Adds behavioral details beyond annotations: describes returned fields, mark_read effect on subsequent calls, and polling suitability. Annotations already declare read-only and idempotent; description adds value without contradiction.

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

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

Concise 4-sentence description, front-loaded with purpose, no wasted words. Each sentence adds essential information.

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

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

Covers tool purpose, returned fields, filtering, mark_read behavior, and alternative access. Despite no output schema, key aspects are addressed. Suitable for a read-only list 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?

Adds context beyond schema: explains how mark_read affects future calls, gives example for type filter. Schema coverage is 100%, but description enhances understanding of parameter 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?

Description clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields. Differentiates from siblings like search and list_subscriptions by focusing on alert feed events.

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

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

Description explains when to use (pulling alerts, filtering, marking read) and provides alternative REST endpoint for scripts/dashboards. Does not explicitly exclude other sibling tools but gives 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?

Beyond the annotations (read only, idempotent), the description explains that the tool fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), describes fallback behavior, patent API limitations, and return format including citation URIs. This adds substantial behavioral context.

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

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

The description is information-dense and well-structured, starting with example queries. While not extremely concise, every sentence provides essential information. Minor fluff could be trimmed but overall efficient.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats) and the lack of an output schema, the description thoroughly covers what the tool does, how it handles failures, and what it returns. It is complete for an aggregation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining accepted formats for 'since' (ISO date or relative shorthand with examples), and clarifies that 'value' can be ticker or CIK. It doesn't fully compensate for enum-only type but still provides useful context.

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

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

The description clearly states that the tool provides a change feed for a company in a specified window, with examples of user queries. It also distinguishes itself from the sibling tool entity_profile.

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

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

The description explicitly gives example queries that should use this tool, explains the fallback logic for news sources, and tells the user to use entity_profile when a static profile is needed, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false. Description adds value by explaining scoping by identifier and persistence duration (24h for anonymous, persistent for authenticated). Could mention overwrite behavior but overall sufficient.

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

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

Description is concise, three sentences long, with front-loaded purpose. Every sentence adds value without redundancy.

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

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

For a simple key-value storage tool with no output schema, the description covers use case, storage semantics, persistence, and related tools. No gaps identified.

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

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

Schema covers both parameters (key, value) with descriptions and examples. Description doesn't add significant extra meaning beyond schema; baseline 3 is appropriate.

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

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

The description uses specific verb 'Save' and resource 'data', clearly indicating it stores key-value pairs. It distinguishes from sibling tools recall and forget by mentioning them for retrieval and deletion.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides context for persistence differences (authenticated vs anonymous) and pairs with recall/forget. No alternative tools needed beyond those mentioned.

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 and idempotent. Description adds internal cascading through endpoints and specifics of what each type returns (ticker, CIK, RxCUI, etc.). No contradiction.

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

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

Well-structured with examples first, then purpose, then type details. Somewhat long but every sentence adds value. Could be slightly more concise without losing information.

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

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

No output schema, but description thoroughly explains return values per type. Covers both entity types and their identifiers. Complete for the tool's functionality.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds further meaning by detailing acceptable inputs per type and mentioning auto-disambiguation, going beyond basic schema.

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

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

The description explicitly states it resolves names to canonical IDs with examples. It distinguishes itself from sibling tools by positioning as the 'first' tool to use when needing an ID, and it explains it replaces several manual 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?

Clearly says 'Use FIRST whenever you have a name but need an ID.' Provides guidance on supported types and input formats. Does not explicitly mention when not to use, but the context is clear.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it probes multiple entities, ranks, and returns a ranked list with score, confidence, signal density. This provides useful behavioral context beyond annotations, such as the ranking behavior and internal use of ai_visibility_check. No contradictions.

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

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

The description is two sentences long, front-loaded with the main purpose, and every sentence adds value. No unnecessary words.

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

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

With no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It also explains the internal mechanism. It could be slightly more detailed about the scoring scale, but it is sufficient for typical use.

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

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

Schema coverage is 100%, but the description adds value by noting that the first entity in the array is treated as the 'subject' for narrative and that the 'anthropic' model requires an API key. This clarifies usage beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and provides a specific verb and resource.

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 useful for competitive AI-marketing audits and gives an example question. It implies not to use when only a single entity is needed (use ai_visibility_check instead). However, it does not explicitly mention when to avoid this tool or list alternative sibling tools like compare_entities.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral context: bundlephobia first measurement can take 5-30s, partial failures are handled gracefully via sources_failed field. No contradiction with annotations.

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

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

Well-structured with a front-loaded summary, then detailed breakdown of data sources, usage, ecosystem scope, and behavior. Every sentence adds useful information, though slightly verbose but efficient.

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

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

Despite no output schema, the description thoroughly explains the return structure (summary block, advisories, links, alternative versions) and handles partial failures, making it fully informative for an agent.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining default version behavior and accepting scoped packages, enhancing understanding beyond the schema.

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

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

The description clearly states the tool performs a composite check for npm packages across deps.dev and bundlephobia, answering questions about safety, popularity, and size. It distinguishes from all listed sibling tools, which cover unrelated domains like AI visibility or Pipeworx.

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

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

Provides explicit when-to-use scenarios (e.g., 'is X safe / popular / small') and clarifies the NPM-only scope in v1, with fallback guidance for other ecosystems. Lacks explicit mention of alternative tools among siblings, but none compete directly.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds no additional behavioral context beyond the annotations, but does not contradict them.

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

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

The description is extremely concise at two words, but this brevity sacrifices clarity and completeness. It is not appropriately structured for a search tool with multiple parameters.

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

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

Given the low schema coverage, lack of parameter guidance, and presence of many sibling tools, the description is insufficient for an agent to fully understand the tool's scope and 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?

Schema description coverage is only 40%, and the description does not explain any parameters beyond what the schema provides. The description adds no semantic value to parameters like 'query', 'page', or 'page_size'.

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 'Full-text search' is vague and does not specify what is being searched (e.g., products, documents). It reads as a tautology of the tool name and title, and does not differentiate from siblings like 'search_within' or 'product'.

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 no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are given.

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

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

Annotations already indicate safe, idempotent, read-only behavior. Description adds valuable internals: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and character offsets for verification.

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

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

Well-structured with front-loaded purpose, then usage, then technical details. Every sentence adds value. Slightly long but appropriately so for a complex tool.

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

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

Covers all aspects: input, output (passages with offsets/scores), limits, embedding details, and pairing guidance. No output schema but description sufficiently explains return values.

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

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

Schema coverage is 100% (all params described), so baseline is 3. Description adds extra: default value for limit (5), example queries for query param, and reinforces max char limit for text.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article, tool result). It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and that it is for large 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?

Provides explicit guidance on when to use (record too big for prompt) and pairs with a specific sibling tool. Lacks explicit when-not-to-use but context is clear.

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

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

Adds significant context beyond annotations: authentication requirements (Pipeworx OAuth account), delivery channel limits (SMS 10/day), and that the feed is always on. 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?

Well-structured with a clear first sentence, followed by auth, types, and delivery details. Each sentence provides essential information, though slightly lengthy.

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?

Comprehensive for a creation tool: covers auth, all types with examples, delivery options with limits and alternatives, and the return value. No output schema needed as return is simple ID.

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

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

The schema has 100% coverage, but the description enriches parameters with examples and explanations (e.g., sec_8k item codes, delivery constraints). Adds meaning beyond the schema's property descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the ID. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying the action and outcome.

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

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

Provides clear context for when to use (proactive monitoring) and mentions the always-on feed pull as an alternative. Lacks explicit when-not cases, but 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?

Annotations already indicate safe, idempotent, open-world. Description adds behavioral context: returns example questions with tool calls, no modification. No contradiction.

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

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

Packed with useful info, front-loaded with trigger phrases. Slightly long but each sentence adds value. Could trim redundant phrases.

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

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

No output schema, but description explains return structure (category-bucketed examples with exact tool+argument) and mentions live catalog. Complete for onboarding function.

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 'topic' is fully described in schema (100% coverage). Description adds meaning: effect of omitting vs providing topic, lists valid values, and explains output variation.

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

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

The description clearly states it returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and search.

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

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

Explicitly says to use it 'FIRST when you do not yet know what Pipeworx can do' and to learn meta-tools. Describes optional topic filtering. Lacks explicit when-not-to-use, but context is sufficient.

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

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

Annotations indicate a write operation (readOnlyHint: false) but nondestructive (destructiveHint: false) and idempotent (idempotentHint: true). The description adds rich context beyond these: ownership enforcement, the distinction between deactivation and deletion, and the preservation of historical events. This fully informs the agent about what happens during invocation.

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, each serving a distinct purpose: stating the action, imposing a constraint, and explaining the behavioral outcome. No word is wasted, and the most important information is 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 simple signature (one required string parameter, no output schema), the description thoroughly covers all essential aspects: the action, ownership requirement, side effect (deactivation), and persistence of historical data. An agent can confidently invoke this tool with only the provided information.

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

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

The input schema covers 100% of parameters with a clear description for 'id'. The tool description repeats the parameter name but adds no new semantic information beyond what the schema already provides. With full schema coverage, the minimum viable score is 3, and there is no added value.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes the tool from its sibling 'subscribe' by specifying the primary function. It also clarifies the scope (ownership enforced) and the non-destructive behavior (deactivation instead of deletion), leaving no ambiguity.

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 a key condition ('Ownership is enforced — you can only cancel your own subscriptions') and explains the effect on data. However, it does not explicitly mention when not to use this tool or point to alternatives like 'recent_alerts' for viewing historical events, which would be helpful for full 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 adds significant behavioral context beyond annotations: it returns a verdict with five options, explains the two processing pipelines (structured EDGAR vs grounded pipeline), and mentions it replaces multiple sequential calls. Annotations already declare it read-only, idempotent, and non-destructive, which alignment is consistent.

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

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

A single paragraph of about 5 sentences, front-loaded with trigger phrases and then explains the process. Each sentence adds value, though a slightly more structured format (e.g., bullet points for the return value) could improve readability.

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

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

Despite no output schema, the description fully specifies the return value: verdict list, actual value with citation, and reasoning. It explains both specialized and fallback pipelines, leaving no gaps for an agent to understand the tool's behavior.

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

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

Both parameters are fully described in the schema, and the description adds valuable context: examples for claim, and for tolerance_pct explains its role in overriding implied tolerance with specific use cases (e.g., 1-2 for hallucination detection).

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 begins with natural-language triggers and clearly states the tool's purpose: verifying factual claims against authoritative sources. It distinguishes between company-financial and other claims, setting it apart from sibling tools like search or entity_profile.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides detail on claim types and pipelines, though it could explicitly mention when not to use or direct to alternatives.

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