Ripe Stat

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

Annotations already mark it as readOnly, idempotent, and non-destructive. The description adds value by specifying data is drawn from RIR records (inetnum/aut-num objects), which clarifies the underlying data source and reliability. No contradictions present.

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

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

The description is only two sentences, yet it packs example queries, the tool's function, data source, and usage suggestion. No extraneous text; every sentence earns its place.

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

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

Given the presence of an output schema, comprehensive annotations, and a single well-described parameter, the description fully covers what the tool does, when to use it, and what data to expect. Nothing essential is missing.

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

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

Schema coverage is 100% with a single 'resource' parameter described as 'IP, prefix, or ASN'. The description enriches this with examples like '8.8.8.0/24' and contextualizes usage (e.g., 'report spam from [resource]'), going beyond the schema's minimal description.

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

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

The description explicitly states the tool returns official abuse-contact email(s) for IP, prefix, or ASN from RIR records. It provides natural language examples like 'abuse contact for IP [X]' and 'report spam from [resource]', making the purpose unmistakable. No sibling tool overlaps, so differentiation is inherent.

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 closes with 'Use for spam/abuse/DDoS report routing,' which clearly indicates when to apply the tool. While it doesn't explicitly list exclusions or alternatives, the context is sufficient given that no alternative abuse-contact sibling exists.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the default model is free, probing Anthropic requires a BYO API key with costs paid directly, and the return format is outlined. No contradictions with annotations.

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

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

The description is three sentences, each serving a purpose: first sentence states the core action and output, second sentence details models and cost, third sentence lists return structure and use cases. It is front-loaded and concise with no filler.

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

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

Given 4 parameters (1 required), no output schema, and absence of rate limit or error info, the description covers the main functionality, costs, and return shape. It lacks discussion of timeouts, failure modes, or restrictions (e.g., entity length limits), but overall it is sufficiently complete for this tool's complexity.

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

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

Schema description coverage is 100%, but the description adds meaning by explaining the default model for 'models', the optional 'context' for disambiguation, and the 'entity' parameter's expected inputs. It clarifies that 'workers-ai' is free and 'anthropic' requires '_apiKey'. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: probing one or more LLMs to score visibility (0-100) per model for a given entity. It distinguishes from siblings by specifying the unique capability of multi-model visibility scoring, with an example use case and default model. Sibling tools like 'scan_competitor_ai_presence' may overlap but this one focuses on score-based auditing.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional API key. However, it does not explicitly state when not to use this tool or suggest alternative sibling tools, leaving some ambiguity for the agent.

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

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

Annotations already show readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context: returns structured answer with stable citation URIs, routes to 4,482 tools, is fast, and is the default entry point. No contradiction with annotations.

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

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

The description is fairly long but front-loaded with key instructions. Every sentence adds value: preference over web search, list of domains, mechanism, examples, comparisons to siblings. Could be slightly tighter but 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 (many sources, sibling tools), the description is comprehensive. It covers what it does, when to use, how to use, and alternatives. No output schema needed as return format is described (structured answer with citations).

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

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

Schema has 100% coverage (6 parameters all described as aliases for question). Description provides examples of question phrasing (e.g., 'current US unemployment rate'), enhancing understanding beyond the schema's bare descriptions. Baseline 3, but examples add 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 routes questions to thousands of sources for structured data, listing specific domains (SEC filings, FDA, FRED, etc.) and providing concrete examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by noting when to use each.

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 gives trigger phrases ('what is', 'look up', etc.). It also provides when to step up to alternatives (hallucination-resistant answers with grounded, broad/multi-part with deep_research) and notes it works on every tier.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds substantial behavioral detail: same routing as ask_pipeworx, extraction step, structured output with evidence and refusal reasons. No contradiction with annotations.

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

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

Description is detailed but front-loaded with purpose and usage. Could be slightly more concise, but every sentence adds value. 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 (routing to many tools, extraction, refusal reasons), the description covers key aspects including output format and cost trade-off. No output schema, but description compensates by explaining return fields.

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 describes all 6 parameters with 100% coverage, describing aliases for question. Description adds minimal additional meaning beyond 'Your question in natural language', which is already in schema. Baseline holds.

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 provides hallucination-resistant answers for high-stakes reads, and distinguishes from the sibling tool ask_pipeworx by explaining the extraction step and refusal behavior.

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

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

Explicitly states when to use (high-stakes reads, when answer will be quoted/cited/acted on) and when to prefer ask_pipeworx instead (casual lookups), with clear rationale.

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, covering the safety profile. The description adds value by specifying the data source (RIPE RIS route collectors), which is relevant for understanding reliability and scope.

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, focused sentence with alternative phrasings and a use case. It is efficient and front-loaded with the core purpose, though the structure could be slightly improved for readability.

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

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

Given the simple single-parameter schema, detailed annotations, and the presence of an output schema (though not shown), the description provides sufficient context about data source and use cases. It does not require explaining return values since the output schema covers that.

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 coverage is 100% and the schema describes 'asn' as 'AS number' with an example. The description does not add further detail about the parameter beyond implying the format, so it meets the baseline for a well-documented 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 that the tool returns BGP peers/neighbours of a given AS from RIPE RIS, with alternative phrasings ('who does [ASN] peer with') and a specific use case ('transit/peering analysis'). It is precise and distinguishes from siblings like 'as_overview' or 'bgp_state'.

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 the tool ('Use for transit / peering analysis, network topology mapping'), providing clear context. However, it does not mention when not to use it or list alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by listing the return fields (holder, country, AS type, allocation date) which aligns with the read-only, idempotent nature. 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 extremely concise: a single sentence that includes example queries, return fields, and usage context. It is front-loaded with actionable queries and wastes no 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 presence of an output schema and rich annotations, the description is complete. It covers what the tool does, the input format, and the return values, leaving no gaps for an AI agent.

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

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

The single parameter 'asn' is fully described in the schema (coverage 100%). The description adds value by providing examples of valid inputs (e.g., 'AS15169' or '15169') and clarifying the expected format.

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

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

The description clearly states the tool's function: providing a summary for an ASN including holder, country, type, and allocation date. It uses specific verbs and resource, and includes example user queries that directly map to the tool's purpose.

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

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

The description provides example queries and states the use cases (network attribution, BGP analysis) but does not explicitly specify when not to use it or compare with siblings.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing resolution behavior, fan-out logic, safety short-circuits, market closure handling, spread warnings, and cancellation rule parsing. This provides comprehensive behavioral transparency.

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

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

The description is front-loaded with the core purpose and use cases. Despite its length (multiple paragraphs), it is well-structured with clear sections for classifiers, fan-out examples, response shapes, safety, and rule risks. It earns its length given the tool's complexity, but could be slightly more concise.

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

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

Given that there is no output schema, the description thoroughly explains return values and states: market fields, analysis, evidence, resolver contract, parent events, news fields, safety statuses, and cancellation rules. It covers all necessary context for an agent to use the tool correctly.

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

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

The input schema has 100% coverage of parameters, but the description adds meaningful context: it explains that the 'market' parameter accepts slugs, URLs, or question text; it elaborates on 'depth' (quick vs thorough) and 'include_raw' (summarized vs full payloads). This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: to research a Polymarket bet by pulling relevant Pipeworx data. It uses specific verbs ('Research', 'pull') and identifies the resource ('Polymarket bet'). It also provides typical use cases ('Use for...'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly lists when to use the tool ('Use for...'), giving clear context. However, it does not explicitly mention when not to use it or point to specific alternatives among the sibling tools, though the 'USE FOR' statements effectively guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context: 'origin ASNs and AS-path lengths currently announcing a resource on the global BGP table,' confirming the stateless, read-only nature. No contradictions, and description adds useful behavioral detail 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?

Description is extremely concise and well-structured: it front-loads common query patterns, then states the core purpose and use cases. Every sentence adds value, no redundancy. Ideal length for an agent to quickly parse.

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

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

With a single required parameter, 100% schema coverage, and an output schema available, the description covers all necessary context: purpose, input format, common use cases, and behavioral traits. Nothing is missing for this tool's complexity.

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

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

Schema coverage is 100% with `resource` described as 'IP, prefix, or ASN'. Description reinforces this and adds concrete examples (e.g., '8.8.8.0/24', 'AS15169') in an examples array, providing format guidance beyond the schema's minimal description. This extra context earns a 4 rather than a 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?

Description clearly defines the tool's function: returns BGP routes, origin ASNs, and AS-path lengths for a resource. It provides specific query patterns (e.g., 'BGP routes for [prefix]') and use cases (hijack detection, audit, anycast discovery), distinguishing it from siblings like `as_overview` and `prefix_overview`.

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 explicitly lists use cases: 'detect BGP hijacks, audit route propagation, find anycast announcers.' It also shows typical query formats. While it doesn't explicitly exclude alternative tools, the sibling list suggests clear differentiation, so guidance is strong but not exhaustive.

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

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

Annotations already indicate readOnly, idempotent, openWorld. The description adds valuable context: off-calendar fiscal year handling, sorted results for 'largest'/'most' queries, and citation URIs. No contradictions.

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

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

The description is front-loaded with common query examples and is well-structured, though slightly verbose. Every sentence contributes meaning (sources, special handling, efficiency claim), earning its place.

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

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

The description fully covers input requirements, data sources, behavioral nuances (sorting, citation URIs), and efficiency benefits. No output schema exists but the description adequately describes return type. No gaps for a comparison tool.

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

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

Schema covers both parameters (100% coverage). The description adds semantic context: examples for company (tickers like AAPL) and drug (names like Ozempic), and explains that type determines data sources and value formats.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, matching common query patterns like 'Compare X and Y'. It specifies data sources (SEC EDGAR for companies, FAERS/FDA for drugs) and distinguishes from siblings like entity_profile by emphasizing efficiency.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 sequential lookups, providing clear when-to-use guidance. Context implies when not to use (single entity lookups should use entity_profile).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds substantial behavioral context: it decomposes questions, routes to 4,482 tools in parallel, returns a findings packet with evidence, confidence, source, citations, and gaps for unanswered facets. It also mentions expected latency (15-60s) and clarifies it is not open-web search. No contradictions with annotations.

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

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

The description is detailed and well-organized with critical usage advice at the beginning. It is slightly long but every sentence provides necessary context. It efficiently communicates purpose, limitations, and behavioral specifics without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains the return format (findings packet with evidence, confidence, source, citations, gaps) and behavior. It covers all essential aspects for an agent to understand what to expect, though some specifics about the exact response structure are omitted.

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

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

The input schema has 100% description coverage for both parameters. The description adds value by explaining that depth maps to specific numbers of facets (quick=3, standard=5, thorough=8) and that the question can be broad/multi-part. This goes beyond the schema's simple enumeration, 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 clearly states that this tool performs 'grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' in one call, emphasizing it is not open-web search. It effectively distinguishes from sibling tools like ask_pipeworx by noting differences in scope and method.

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 (broad/multi-part questions over structured data) and when not to (single lookup: use ask_pipeworx; breaking/current news: prefer ask_pipeworx). It also notes account requirements and alternatives, providing complete usage 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, idempotentHint, and non-destructive nature. The description adds behavioral details: returns top-N relevant tools with full input schemas and curated examples, and states that each result is ready to call directly without second schema lookup. 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 somewhat lengthy but every sentence adds value. It front-loads the core action and provides concrete flow guidance. Could be slightly more concise, but for the complexity of the tool, it's 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 has 6 parameters (1 required), full schema coverage, no output schema, but the description explains the qualitative return value (top-N relevant tools with names, descriptions, schemas) and mentions limit. It could be more specific about response structure or pagination, but it's adequate for a discovery 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 the 'query' parameter's purpose as a natural language description and listing aliases, and defines default and max for 'limit'. However, it doesn't add more nuance that the schema misses.

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

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

The description clearly states 'Find tools by describing the data or task' and provides a comprehensive list of example domains (SEC filings, FDA drugs, etc.), making the tool's purpose unmistakable. It also distinguishes itself from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set'.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by specific categories. It also advises to call this tool FIRST before other tools, providing clear when-to-use and exclusion guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds detailed behavioral context: fans out across multiple sources, returns specific fields, notes USPTO API sunset with soft-fail behavior. No contradictions.

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

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

The description is relatively long but each sentence adds value. It front-loads with examples and then provides structured guidance. Slightly verbose but highly informative.

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

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

No output schema, but the description compensates by listing all return types (cik, filings, fundamentals, patents, news, LEI). Given tool complexity, it is sufficiently complete for an agent.

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

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

Schema coverage is 100%. The description enriches parameter meaning with examples (ticker or CIK) and explicit constraint that names are not supported, providing more value than 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: 'full cross-source profile of a US public company in ONE parallel call.' It uses trigger phrases like 'Tell me about X' and explicitly distinguishes from chaining single-pack lookups.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity for names, providing clear when-to-use and when-not-to.

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 readOnlyHint false, so the description's 'Delete' is consistent but adds limited new behavioral insight beyond confirming it removes a memory. The mention of clearing sensitive data provides minor additional context, but overall the description does not significantly expand on the annotations.

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

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

The description is extremely concise: one sentence defining the action, one sentence specifying use cases, and a final sentence connecting to siblings. No redundant information; every sentence earns its place. Well-structured and front-loaded.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description provides all necessary context: what it does, when to use it, and its relationship to other tools. It is fully complete for the tool's complexity level.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description repeats 'by key' without adding further semantics like format, constraints, or examples. Baseline 3 is appropriate as the schema already documents the parameter adequately.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying both the action and resource. It mentions pairing with 'remember' and 'recall', which implies its complementary role, but does not explicitly distinguish it from siblings like 'recall' which retrieves. Thus purpose is clear but not fully distinctive.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', indirectly guiding the agent to avoid using this tool when storage or retrieval is intended. This meets the criteria for explicit usage context.

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

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

Annotations already declare it as read-only, idempotent, and non-destructive. The description adds process details (fetching, extracting, emitting) and deployment context (site-root/llms.txt). No contradictions, but could mention potential rate limiting or errors.

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

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

The description is concise (3-4 sentences) with front-loaded purpose, efficient coverage of process, and targeted use cases. 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 straightforward tool with two parameters and no output schema, the description adequately covers output format (text blob) and content (title/description/key links). It could briefly mention the exact structure of the llms.txt, but overall it's sufficient for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add significant new meaning beyond 'any URL' and does not elaborate on max_links behavior or constraints.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, with specific actions: fetching, extracting title/description/key links, and emitting standard markdown. It distinguishes itself from sibling tools by its unique 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 provides explicit use cases: getting client's site indexed, drafting for own project, or auditing competitor's AI visibility. However, it does not mention when not to use or suggest alternative tools, which would enhance 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, openWorldHint, idempotentHint, and destructiveHint. The description adds a critical caveat: 'registration-based geo, not GeoIP — accurate for ownership country but not necessarily the host's physical location.' This provides behavioral nuance beyond annotations, though annotations already cover safety.

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

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

Three sentences: first presents query patterns, second introduces the tool, third explains limitations. Every sentence is informative with no redundancy. Efficiently front-loaded.

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

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

Given the tool's simplicity (1 param, output schema present), the description covers purpose, usage, and important behavioral limitations. No gaps remain for effective agent invocation.

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

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

The sole parameter 'resource' has a schema description ('IP or prefix') and the description provides concrete examples ('8.8.8.8', '1.1.1.0/24'), aiding format understanding. Schema coverage is 100%, so baseline is 3; the examples elevate it to 4.

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

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

The description uses specific verbs ('geolocate', 'country geolocation') and identifies the resource type (IP or prefix derived from RIR data). It distinguishes this tool from GeoIP, clarifying its unique scope. Example queries further reinforce the purpose.

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

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

Explicitly states when to use ('compliance / jurisdiction questions where registry truth matters') and when not to use ('not necessarily the host's physical location'). This helps the agent choose alternatives if physical location is needed.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds return fields and default active-only behavior, but not significant beyond annotations.

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

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

Three sentences, front-loaded with main action, no wasted words. Efficient and clear.

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

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

No output schema, but description lists return fields (id, type, params, etc.) which is sufficient. Lacks mention of pagination or limits, but acceptable for a simple 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?

Schema covers the only parameter (include_inactive) with description. The tool description reinforces default filter but does not add new semantic meaning beyond the schema.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly indicates when to use and refers to alternative actions (adding, cancelling).

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. The description adds value by specifying the returned data (prefix and ASN) but does not disclose additional behavioral traits like rate limits or authentication needs. 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 extremely concise, using a single paragraph that includes example queries and use cases. Every sentence adds value, with no wasted words.

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

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

Given the simple single-parameter input and the presence of an output schema, the description fully covers the tool's behavior and use context. It is complete for an AI agent to understand and invoke correctly.

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

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

The input schema covers the single parameter with description 'IPv4/IPv6 address' (100% coverage). The description adds example values but no further semantic detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states that the tool returns the allocated prefix and originating ASN for an IP address, and provides example queries. It differentiates its purpose through specific use cases (DDoS source attribution, hosting-provider lookup) but does not explicitly contrast with 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 explains when to use the tool ('which network owns this IP', DDoS attribution, hosting-provider lookup) but gives no guidance on when not to use it or how it differs from alternatives like asn_neighbours or prefix_overview. Clear context without 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?

Beyond the annotations (which only indicate readOnlyHint, idempotentHint, etc., all false), the description adds key behavioral details: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also explains that feedback affects the roadmap and is read daily. These details disclose important constraints and effects not in annotations.

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

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

The description is concise at about 5 sentences, each with a clear purpose: purpose, use cases, best practices, rate limit, and quota. It is front-loaded with the main action and immediately conveys the tool's value. No redundant or irrelevant 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 tool's simplicity (3 parameters, nested objects, no output schema), the description covers all essential aspects: purpose, when to use, how to write feedback, and behavioral constraints. However, it does not mention what happens after submission (no confirmation or response expectation). Since the tool is one-way feedback, the lack of return value detail is minor but prevents a 5.

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

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

Although the input schema already describes each parameter (coverage 100%), the description adds extra semantic guidance: for 'type' it redefines the enum values with practical explanations; for 'message' it advises specificity and length; for 'context' it clarifies the optional structured context. This adds value beyond the schema's technical 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the actions (report bugs, request features, give praise). It distinguishes this tool from siblings like 'abuse_contact' and 'ask_pipeworx' by focusing on internal product feedback.

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 the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises against pasting end-user prompts and recommends describing issues in terms of Pipeworx tools/packs, providing clear usage context without needing to reference siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data source, privacy, and caching behavior beyond annotations.

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

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

The description is concise and well-structured: core function first, then bullet-pointed use cases, then technical details. Every sentence adds value with no fluff. It is front-loaded and efficient.

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

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

Given the tool's simplicity (1 parameter, no output schema, rich annotations), the description covers all necessary aspects: what it returns, window options, use cases, data source, privacy, caching. It is fully complete for an agent to select and invoke correctly.

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

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

The input schema provides full parameter coverage (window with enum and description). The description adds interpretation context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the schema, but the schema already does most of the work.

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: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It specifies the resource (call data on Pipeworx) and the action (returns), distinguishing it from sibling tools that focus on individual entities or queries.

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

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

The description explicitly lists three use cases with bullet points: discovering hot data sources, confirming popular/canonical tools, and seeing alignment with agent needs. It also implies when not to use (e.g., for specific queries) and provides context for window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: how it walks child markets, checks ordering, computes partition check, uses Jaccard similarity for cross-event, filters placeholders, and performs fill check against live CLOB depth. No contradictions with annotations.

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

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

The description is dense and well-structured: starts with requirement, then explains modes, their inner workings, semantic anchor, partition filter, response structure, fill check, and cross-reference to another tool. While thorough, some redundancy could be trimmed (e.g., repeated mention of 'event mode' details). Still, every sentence provides value, earning a high score.

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

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

No output schema is provided, but the description compensates by detailing the response structure: opportunities[] fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check fields. It covers prerequisites (requires event or topic), edge cases (no args fail, placeholder filtering), and integrates with sibling tool for custom sizing. Complete for 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 description coverage is 100% (both parameters have descriptions). The tool description goes far beyond by explaining the purpose of each parameter (event vs topic), giving examples of valid values (e.g., 'fed-decision-may-2026'), and detailing the behavior triggered by each mode. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event for single-event, topic for cross-event) and differentiates from sibling tools like polymarket_edges, polymarket_fill_risk, etc., by specifying its unique arbitrage detection logic.

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

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

Explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Warns that calling with no args fails. Points to an alternative: 'For custom sizing use polymarket_fill_risk.' No ambiguity about usage context.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false; the description aligns with these and adds extensive behavioral context: caching policy (1h KV), model details (lognormal, GDELT, partition_overround), how edge_pp_net and kelly_fraction are calculated, slippage assumptions, and filtering logic. 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 long but well-structured: it opens with the core purpose, breaks into three model families, explains knobs, and closes with response structure. While dense, every sentence adds value for a complex tool. Minor verbosity could be trimmed, but it remains efficient given the depth.

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

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

Given 9 parameters, no output schema, and three complex segments, the description covers all necessary context: response structure (by_segment, diagnostics), edge cases (Fed bets excluded from ranking, empty segment explanations), and parameter interactions (tradeable-edge knobs). 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 coverage is 100% but the description adds significant meaning beyond field names and types: for example, slippage_pp explains Polymarket's fee structure and recommended adjustments; min_partition_leg_kelly clarifies why min_kelly doesn't filter partitions. Each parameter's description expands on its role in the pipeline.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with the specific use case 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven and structural arbitrage opportunities with detailed model families.

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

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

The description provides explicit guidance on when to use the tool ('what should I bet on today'), describes the three response segments and their filters (tradeable-edge knobs), and explains diagnostics for empty segments. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and not destructive. The description adds significant behavioral context: snapshots are daily, history is bounded by TTL, decay is computed from daily closes, and response structure includes tracking, expired, and snapshot dates. 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, starting with a clear purpose statement, then arguments, then detailed response format, ending with limitations. It is somewhat lengthy 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?

Given no output schema, the description thoroughly explains the return value structure (tracked, expired, snapshot_dates) with field details. It also covers limitations (TTL, snapshot gaps, intraday). For a tool of this complexity, the description is fully complete.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description repeats defaults and ranges for 'days' and 'window' but adds no new meaning beyond the schema. It provides context like 'lookback' and 'snapshot family', which is helpful but not additional semantics.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, addressing the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from siblings like 'polymarket_edges' by focusing on historical trends rather than a single snapshot, using specific verbs and 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 explains when to use the tool: to assess whether a wide edge is fresh or old, which is important for trading decisions. It implies that for current edge data, one would use 'polymarket_edges'. Limitations such as 60-day TTL and intraday granularity are explicitly stated, though no explicit alternative is named.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral details: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage, shares_filled, max_fillable, verdict (clean|degraded|cannot_fill) for single-market; for basket it returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fills, thin_legs, max_clean_notional, and forced_directional_risk. It warns that partial basket fills create unhedged directional positions. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and uses headings for navigation. Every sentence adds value, though a minor reduction could improve conciseness without losing substance.

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

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

With no output schema, the description fully explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single; theoretical_sum, realizable_sum, capture_ratio for basket). It also covers edge cases (thin_legs, forced_directional_risk) and the verdict field. For a 4-parameter tool, this 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 description coverage is 100%, so baseline is 3. The tool description repeats much of the schema's explanations (e.g., side defaults, size_usd interpretation). It adds some context like 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional S' for basket, but overall does not significantly augment the schema's already thorough 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 does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by advising use before acting on their signals or trades above ~$500.

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

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

The description provides explicit guidance on when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about pitfalls like thin books and partial basket fills converting arbs into unhedged positions, giving clear context for usage.

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

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

The description discloses extensive behavioral traits beyond annotations: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counts), and edge cases (non-equivalent bet shapes, semantic mismatch). It fully informs the agent of the tool's behavior and limitations. Annotations already mark it read-only and idempotent, which aligns.

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

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

The description is dense and front-loaded with the purpose, but it is relatively long (two paragraphs). Every sentence adds value, covering modes, response, safety fields. Could be slightly more structured (e.g., bullet points), but it remains clear and comprehensive. Not concise enough for a perfect 5.

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 no output schema, the description does a good job explaining the response (leg-by-leg prices, spread, safety fields). However, it lacks explicit structure or example of the response JSON, which would enhance completeness. Still, it covers all critical behavioral aspects and edge cases, making it largely complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context by explaining how topic maps to events, how explicit params override, and lists the pre-mapped topics. This adds meaning beyond the schema, such as the list of topic strings and the overrides behavior. A score of 4 reflects valuable addition without being excessive.

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. It uses specific verbs ('compute', 'compare') and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue arbitrage. The two modes (topic and explicit) are explained, making the purpose unambiguous.

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

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

The description provides detailed usage guidance: when to use each mode, that pre-mapped topics often return compatibility warnings, and when spreads are meaningless (e.g., temporal misalignment). It does not explicitly compare to alternatives but implicitly covers when not to use the tool. A slight deduction for not explicitly naming sibling 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 readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description adds value by detailing the data categories (BGP announcements, origin ASes, allocation history), providing behavioral context beyond the annotations 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?

Two sentences, front-loaded with examples and core purpose, followed by usage guidance. No extraneous information; every sentence is purposeful.

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 (single parameter, high schema coverage, good annotations, and an output schema), the description adequately covers purpose, content, and usage context. It is complete without requiring further detail.

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

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

Schema coverage is 100% and the description adds minimal extra semantics beyond the schema's parameter description. The example formats are helpful but do not significantly extend understanding of the parameter's meaning.

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

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

The description provides explicit examples ('Prefix overview for [CIDR]') and clearly states it delivers a comprehensive summary including BGP announcements, origin ASes, and allocation history. It distinguishes itself from chaining bgp_state + whois, making the purpose unambiguous.

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

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

Explicitly advises using this tool to understand a whole IP block instead of chaining bgp_state + whois, offering a clear alternative. However, it does not explicitly state when not to use it (e.g., for single data points), though the context is implied.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds key context: scoping to an identifier (anonymous IP, key hash, account ID) and the retrieval behavior with optional key listing. 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 three sentences, front-loaded with the main action, and every sentence adds essential information without redundancy.

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

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

Given no output schema, the description does not specify the return format or behavior for missing keys. However, it covers scoping, pairing with siblings, and the key omission behavior. Minor gaps prevent a perfect score.

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

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

Schema coverage is 100% with a parameter description. The description reinforces usage, explaining that omitting the key lists all saved keys, and provides examples in the schema. It adds value beyond the schema by clarifying the dual behavior.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys. It uses specific verbs ('retrieve', 'list') and resources ('value saved via remember', 'all saved keys'), and distinguishes it from sibling tools 'remember' and 'forget'.

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

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

The description explicitly says when to use: to look up context stored earlier. It explains when to omit the key (to list all keys) and pairs the tool with 'remember' and 'forget', guiding the agent on 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?

Explains the side effect of mark_read (mutating read state) beyond the annotations which declare readOnlyHint and destructiveHint false. This adds important behavioral context. 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?

Extremely concise with four sentences front-loading purpose, followed by filtering and side effects, and ending with an alternative method. 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?

Covers core return fields, filtering options, and the mark_read behavior. Lacks details on pagination or full response structure, but given the lack of an output schema, the description is sufficiently informative 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 with an example for type ('sec_8k') and clarifies the effect of mark_read on subsequent calls. This goes beyond the schema's description.

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

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

The description clearly states it pulls fired events from the subscription feed and specifies the fields included (source, citation_uri, raw payload). It distinguishes itself from siblings like 'list_subscriptions' through the focus on alerts, but does not explicitly contrast with sibling tools.

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

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

Provides clear guidance on filtering by type, since, and using mark_read to manage read state. Also mentions polling and an alternative HTTP endpoint. Does not explicitly state when not to use or directly compare with sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral details: it fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains fallback logic, and mentions soft-failure for PatentsView. This goes beyond annotations, though it does not discuss rate limits or pagination. Still, it is highly transparent.

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

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

The description is front-loaded with example queries that immediately convey usage. It is well-structured, covering purpose, sources, parameters, return structure, and alternatives. While somewhat lengthy, every sentence adds information; minor trade-off for clarity. A 4 reflects good organization with slight room for trimming.

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

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

Given the tool's complexity (multiple data sources, fallback logic, flexible date formats) and the absence of an output schema, the description provides a complete picture. It explains the fan-out behavior, return structure (grouped changes, total_changes, citation URIs), and parameter acceptance. No obvious gaps remain.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds further value by explaining that 'since' accepts ISO dates or relative shorthand (with examples like '7d', '30d', '1y'), and that 'type' only supports 'company'. This extra context improves parameter understanding beyond the schema alone.

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

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

The description clearly states that this tool provides a change feed for a company in recent N days/weeks/months, covering SEC filings, news, and patents. It distinguishes itself from the sibling tool 'entity_profile' by specifying that 'entity_profile' should be used for static profiles, making the purpose unambiguous and contextual.

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 provides example queries for when to use this tool (e.g., 'What's new with X', 'latest on Y') and explicitly states when to use an alternative: 'Use entity_profile instead when you want the static profile'. It also details fallback behavior between GDELT and GNews, giving clear usage context and alternatives.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds key-value pair scoping, authentication-based persistence, and time limits, fully disclosing behavior.

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

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

Four well-structured sentences, front-loaded with purpose, no redundancy, every sentence adds value.

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

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

Despite no output schema, the description fully explains storage semantics, persistence, and integration with sibling tools, leaving no gaps.

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

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

Schema covers both parameters with descriptions; the tool description adds usage examples (e.g., 'subject_property'), enhancing clarity beyond the schema.

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

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

The description explicitly states the tool saves data for later reuse, provides concrete examples, and distinguishes from siblings like recall and forget.

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

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

It clearly explains when to use (discover something worth carrying forward) and how to pair with recall/forget, with explicit persistence durations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond annotations: it explains that each call cascades through several lookup endpoints internally, auto-disambiguates for company names, and provides citation URIs. 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, well-structured paragraph. It front-loads with example queries to quickly convey purpose, then details supported types and their outputs. Every sentence adds necessary information without redundancy. No wasted words, making it efficient for an AI agent to parse.

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

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

Given the tool has no output schema, the description thoroughly explains what is returned for each entity type (ticker, CIK, RxCUI, etc.) and includes citation URIs. It covers both parameters with examples and behavior. For a resolution tool of moderate complexity, this description is fully complete and leaves no ambiguity.

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

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

Schema coverage is 100% with both parameters described in the schema. The description adds value by providing examples of valid inputs (e.g., ticker 'AAPL', CIK '0000320193', company name; brand/generic for drugs) and clarifying auto-disambiguation behavior for the 'value' parameter. It explains that for company, the type accepts ticker, CIK, or name, enhancing understanding beyond the schema's enum and description.

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

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

The description starts with concrete example queries and states the core function: resolving a user-spoken name to the canonical identifier. It specifies supported entity types (company, drug) and what each returns (ticker+CIK+name for company; RxCUI+ingredient+brand for drug). This clearly distinguishes it from sibling tools that use identifiers.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' This gives clear guidance on when to invoke this tool. While it doesn't explicitly state when not to use it, the context implies that if an ID is already available, this tool is unnecessary. It also notes that it replaces 2-3 manual lookups, providing additional usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: it internally calls ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This supplements the annotations with behavioral details 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?

Two sentences, each valuable: first states core purpose and operation, second gives applicability and output format. No filler, front-loaded with key info.

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 4 params fully described in schema and annotations covering safety, the description adequately explains the output format (ranked list with score, confidence, signal density) despite no output schema. The tool's complexity is well-addressed.

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%, providing baseline 3. The description adds meaning: it explains the role of 'entities' (first as subject), 'context' as disambiguation, 'models' with free default, and '_apiKey' condition. It also describes the internal probing behavior, 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?

Description clearly states the tool compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check which is for single entities, making the purpose specific and unambiguous.

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

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

The explanation 'Useful for competitive AI-marketing audits' and the example question provide clear context for when to use. While it doesn't explicitly exclude single-entity scenarios, the mention of 'multiple entities' and the sibling ai_visibility_check allow inference. No alternatives are named, but usage 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds crucial behavioral context: fans out across deps.dev and bundlephobia, partial failures degrade gracefully, and bundlephobia's first measurement may take 5-30s. This exceeds the annotation baseline.

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 but dense and well-structured, front-loading the purpose and usage. Every sentence adds value, but a slightly more structured format (e.g., bullet points for return fields) could improve readability. Still very 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 complexity of a composite check with two external services and no output schema, the description thoroughly covers the return values, error handling (partial failures), limitations (NPM only, timeout), and inputs. No gaps are apparent.

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?

Since schema description coverage is 100%, the baseline is 3. However, the description adds significant value by explaining that scoped packages like '@types/node' are accepted, that version defaults to latest, and by detailing the return object structure (summary, advisories, links, alternative versions). This far exceeds the baseline.

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

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

The description clearly defines the tool as a composite check for deciding whether to add an npm package to a project, combining licenses, advisories, version history, bundle size, and ESM/tree-shake support. It distinguishes itself from sibling tools like deps.dev:version by mentioning NPM ecosystem only in v1.

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 an agent asks about safety, popularity, size, or cost of adding a package. Also provides guidance for other ecosystems (PyPI, Maven, etc.) by suggesting deps.dev:version directly, making the usage boundaries clear.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. Description adds valuable details: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flagging, and offset for verifiability. 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?

Concise yet comprehensive; uses effective structure with examples and technical details. Every sentence earns its place 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?

No output schema, but description covers return values (passages with offsets and similarity scores) and edge cases (truncation). Completely adequate for the tool 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%, and description enriches it: explains query as natural-language, limit range and default, text max chars and truncation behavior. Adds significant value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article) and output details (passages with offsets and scores). It distinguishes itself from sibling ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too big for the prompt and mentions pairing with ask_pipeworx_grounded. Could be slightly more explicit about when not to use or 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?

Beyond annotations, the description discloses significant details: OAuth requirement, subscription id return, feed always-on, delivery constraints (phone verification, 10/day cap, webhook auto-disable after failures), and type-specific examples.

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

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

The description is front-loaded with the main purpose and return value. While it is lengthy, every sentence adds value; it could be more structured but remains 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 complexity (nested objects, no output schema), the description covers core functionality, return value, and multiple edge cases. It could elaborate on error handling but is sufficient for most agents.

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

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

With 100% schema documentation, the baseline is 3. The description adds practical examples and constraints not in the schema, such as phone verification requirement, webhook HMAC signing, and auto-disable condition.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It specifies supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains the required account type (Pipeworx OAuth) and provides guidance on when to use (creating subscriptions) and not (anonymous/BYO accounts). It does not explicitly exclude 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 already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the output structure (category-bucketed examples with tool+argument shapes). No contradictions. The description explains the behavior beyond what annotations provide.

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

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

The description is a single paragraph that packs essential information without redundancy. It is front-loaded with example questions and usage hints. Could be slightly more structured (e.g., bullet points), but it remains concise and clear.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains what the tool returns, how to use it (no arguments or with topic), and its purpose as an onboarding entry point. It is complete given the tool's complexity and 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 coverage is 100% (one optional topic parameter described). The description adds meaning beyond the schema by listing example topics and explaining that omitting topic gives a full spread. This provides extra context for the agent.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions. It uses specific verbs ('Returns category-bucketed example questions') and distinguishes itself from siblings by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without arguments. However, it does not explicitly state when not to use it or contrast with alternatives like discover_tools, though the usage 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?

The description adds value beyond annotations by stating ownership enforcement, deactivation (not deletion), and the availability of historical events via recent_alerts. Annotations already indicate idempotency and non-destructiveness, so the description complements 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?

Three sentences, each providing essential information without redundancy. The main action is front-loaded, and every sentence adds value.

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

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

Given the simple one-parameter tool and presence of annotations, the description covers core behavior, ownership, side effects, and relation to other tools. However, it does not describe the return value or error conditions, which is a minor gap since no output schema exists.

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

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

Schema coverage is 100% and the schema already describes the parameter as 'Subscription id (uuid) returned by subscribe.' The description adds slight context by referencing 'by id' and connecting to subscribe, but does not provide additional semantic detail 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 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from sibling tools like subscribe (creates) and list_subscriptions (lists) by specifying cancellation and ownership enforcement.

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

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

The description explains when to use the tool (to cancel a subscription) and provides ownership constraints ('you can only cancel your own subscriptions'). It also hints at alternatives by mentioning that historical events remain available via recent_alerts. However, it does not explicitly list when not to use it.

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

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

The description discloses data sources (SEC EDGAR + XBRL), the returned verdict types, citation format, and percent delta. Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, and the description adds valuable context without contradiction.

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

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

The description is moderately long but well-structured: it starts with query examples, states the core purpose, then adds scope, output details, and efficiency notes. Every sentence adds value, though it could be slightly tighter.

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

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

Despite the lack of an output schema, the description covers the return types and citation format. Given the complexity of claim verification, the description is comprehensive and leaves no major gaps for an agent to understand usage and behavior.

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

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

Only one parameter 'claim' with a schema description. The description provides natural-language examples that illustrate valid input (e.g., 'Apple's FY2024 revenue was $400 billion'), adding meaning beyond the schema's type and description.

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

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

Description clearly states it performs natural-language claim verification against authoritative sources, with examples of queries. It specifies the domain (company-financial claims) and distinguishes itself from any sibling tools, none of which overlap in functionality.

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

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

Explicitly says when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also notes the current scope (v1 supports company-financial claims). While it doesn't list explicit alternatives among siblings, the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds specific behavioral details: aggregation across all five RIRs, return fields (registrant org, country, abuse contacts, allocation date). 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, well-structured sentence that front-loads the core purpose and includes examples and use cases. No wasted words.

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

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

Given the single parameter, high schema coverage, available output schema, and annotations, the description fully covers what the tool does, its inputs, and its outputs. No gaps.

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

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

The schema covers the parameter resource with 100% description coverage. The description adds value by providing real-world examples (8.8.8.8, AS15169) and clarifying accepted formats beyond the schema description.

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

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

The description clearly states the tool performs whois lookup for IP addresses, AS numbers, or prefixes. It provides specific examples and distinguishes from siblings like asn_neighbours or geoloc by specifying aggregated RIR data and return fields.

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

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

The description explicitly lists use cases: IP ownership, abuse-response, network forensics. It indicates the query types (IP, prefix, AS) but does not explicitly exclude alternatives. Still, it provides clear context for when to use.

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