Ripe Stat

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 value by specifying the data source (RIR records) and output type (official abuse-contact email(s)). No contradictions.

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

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

The description is a single, efficient sentence that front-loads the primary purpose and includes multiple clarifying phrasings. Every part serves a purpose with zero waste.

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

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

Given the low complexity (one required parameter, simple lookup), the description sufficiently explains what the tool does and returns. The presence of an output schema further reduces the need to describe return values.

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

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

Schema description coverage is 100% for the single parameter 'resource' (described as 'IP, prefix, or ASN'). The description adds an example ('8.8.8.0/24') and clarifies the acceptable formats, adding 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 with specific verbs ('contact', 'report') and resources ('IP, prefix, ASN'). It includes alternative phrasings and distinguishes from sibling tools by focusing on abuse contact lookup from RIR records.

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

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

The description explicitly states 'Use for spam/abuse/DDoS report routing', providing clear context. However, it does not mention when not to use the tool or list alternative tools for similar queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by explaining the default model (Workers AI Llama-3.3-70b, free) and that using Anthropic requires an API key passed to a third party. This provides useful behavioral context beyond annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core action and result. Every sentence adds value without redundancy, making it highly 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 no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response, combined view). It covers use cases and parameter details. A slight gap is the lack of explanation about 'confidence' or 'signals' fields, but overall it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that '_apiKey' is for Anthropic and passed directly to api.anthropic.com, 'context' disambiguates entities, and 'models' accepts specific values. 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 function: probing LLMs for visibility scoring of an entity (0-100). It specifies the default model and option for Anthropic. However, it does not explicitly differentiate from similar sibling tools like 'deep_research' or 'scan_competitor_ai_presence', missing some distinction.

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

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

The description provides context for when to use the tool (AI-marketing audits, pre-launch checks, competitive monitoring) and mentions the free default model. However, it lacks explicit when-not-to-use guidance or comparisons to alternative tools among 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 establish read-only, idempotent, open-world behavior. The description adds useful behavior beyond that: it routes questions, fills arguments, returns structured answers with stable citation URIs, works on every tier, and makes one fast call. It also subtly contrasts with the more hallucination-resistant grounded variant, giving agents a realistic sense of base behavior.

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

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

The description is long, but nearly every sentence earns its place: it communicates priority, coverage, examples, alternatives, and tier/performance constraints. It is front-loaded with the most important routing guidance, and the structured list of examples improves scannability.

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

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

For a tool with no output schema, the description covers what an agent needs: when to use it, what it does internally, what kind of answer to expect, how it compares to siblings, and even account-tier behavior. The mention of stable citation URIs and structured answers compensates for the absence of an output schema.

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

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

Schema coverage is 100%, so the schema already documents the question parameter and its aliases. The description reinforces parameter semantics by explaining the input is a natural-language question or request and supplies a varied list of examples that clarify expected phrasing and scope.

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: it routes questions to one of 5,706 tools across 1,493 sources and returns structured answers with citation URIs. It also distinguishes itself from close siblings like ask_pipeworx_grounded and deep_research by naming the exact conditions for stepping up.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', establishes this as the default entry point, and gives concrete when-to-use versus when-not-to-use guidance by pointing to grounded and deep_research. It also provides many concrete example queries.

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 valuable behavioral context beyond the annotations: candidate routing improvements are enabled live only when under test, no candidate is currently active (retired 2026-07-26), and it currently matches ask_pipeworx exactly. It also preempts misinterpretation by stating it 'falls back to nothing' and is a complete router. This transparently discloses the tool's dynamic experimental nature without contradicting the readOnly/openWorld/idempotent hints.

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 identity ('Beta version of ask_pipeworx') and then provides essential beta-specific context: candidate improvements, current inactive status, usage instruction, and a fallback clarification. Every sentence contributes meaningful information, though the exact retirement date is a minor detail that adds specificity without bloat.

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 beta router with no output schema, the description covers the key contextual needs: it states the same response shape, explains the current no-candidate state, and gives invocation guidance. The only minor gap is not detailing what happens if a candidate becomes active mid-conversation, but the description already says results are compared with the stable router, so the agent has enough to use it 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 already provides 100% coverage, documenting `question` and all five aliases (q, text, input, query, prompt). The description adds only that the arguments are identical to ask_pipeworx, which reinforces sameness but does not deepen parameter meaning. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,706 tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by mentioning candidate routing improvements and the experimental edge, making the tool's purpose and scope unambiguous.

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

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

The description explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and clarifies that it is not a fallback but a full working router. It does not explicitly mention when to prefer the stable ask_pipeworx or ask_pipeworx_grounded, but the primary usage condition 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?

Disclosures go well beyond the readOnly/openWorld/idempotent annotations: the tool explicitly refuses rather than inventing answers, returns verbatim evidence quotes, and enumerates all refusal reasons. It also discloses the extra LLM call cost versus the sibling, giving the agent a clear behavioral model.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return shape, refusal semantics, usage cases, and cost trade-off. Key differentiator 'hallucination-resistant' and the sibling comparison are 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?

Despite having no output schema, the description provides the full return structure, explicit refusal reasons, use cases, and cost trade-off. Combined with the safety-related annotations, the agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the free-text question; the description itself adds no parameter-level semantics. Baseline 3 is appropriate when the schema carries full parameter documentation.

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

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

States a specific verb and resource: asking Pipeworx a question in a 'grounded' hallucination-resistant mode. It explicitly differentiates from sibling ask_pipeworx by highlighting that it extracts answers only from tool results and returns evidence and refusals.

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

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

Provides explicit when-to-use guidance: for quoted, cited, or acted-upon answers in high-stakes domains like financial, legal, or medical lookups. It names the alternative ask_pipeworx and says to prefer it for casual lookups due to the extra LLM call cost.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. Description adds the data source (RIPE RIS) and the observational nature, which provides modest additional context beyond annotations.

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

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

Single sentence efficiently packs synonyms, data source, and use cases. No redundancy or fluff.

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

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

For a single-parameter tool with rich annotations and an output schema, the description provides sufficient context about data source and application, making it complete for correct invocation.

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

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

With 100% schema description coverage, baseline is 3. Description reinforces the parameter's role but adds no extra format or syntax details beyond the schema.

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

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

Description clearly states the tool returns BGP neighbours of an AS using RIPE RIS data, with specific synonyms and use cases for transit/peering analysis. Distinguishes itself from sibling tools like as_overview and bgp_state by focusing on neighbour relationships.

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?

Explanation of 'transit / peering analysis, network topology mapping' provides usage context. Does not explicitly contrast with siblings, but the domain-specific language helps agents select appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context by listing the exact fields returned (holder, country, type, date), which goes beyond annotations and helps the agent understand what to expect.

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

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

The description is two sentences plus example queries in quotes. It is front-loaded with the most common use-case queries, and every part contributes to understanding the tool. No redundant or missing 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?

With only one parameter and an output schema available, the description provides sufficient context: it lists the output fields and usage. The tool is simple and the description covers all necessary aspects for correct invocation.

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

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

Schema coverage is 100% with a clear description of the 'asn' parameter. The description adds examples and alternative formats ('AS15169' or '15169'), but this is already implied by the schema. Baseline is 3 because schema does the heavy lifting; description provides marginal additional 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 starts with natural language queries like 'Who owns AS[N]' and 'AS[number] info', then clearly states it returns a summary for an ASN: holder organization, country, AS type, allocation date. It distinguishes itself from siblings like 'asn_neighbours' by focusing on overview rather than neighbors 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 provides example queries and explicitly says 'Use for network attribution, BGP analysis.' It does not explicitly exclude alternatives, but the context makes it clear when to use this tool. Minor improvement would be to mention siblings like 'asn_neighbours' for neighbor information.

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?

Response shapes, resolver contract, parent event extraction, news fallback logic, safety mechanisms for low confidence, wide spread handling, and cancellation rule parsing are all detailed. Annotations (readOnlyHint, idempotentHint) are consistent and description adds significant behavioral depth beyond 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?

Long but well-structured with clear sections and examples. Every sentence adds value; no redundancy. Could be slightly more concise, but organization aids agent parsing. Information density is high.

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

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

Given the complexity (multiple data sources, classification, response shapes), the description covers all facets: input resolution, data fan-out, output structure, edge cases, and safety. No output schema, but response shapes are thoroughly described. Complete for agent 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 covers all 3 parameters with descriptions, but the description adds valuable context: market accepts slug, URL, or text; depth default and effect; include_raw explanation. This enriches understanding beyond the schema's concise 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 researches a Polymarket bet by pulling Pipeworx data. It specifies verbs like 'research' and gives concrete use cases ('should I bet on X'). Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges through its data-gathering focus.

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

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

Explicitly says 'Use for' three scenarios and provides examples of fan-out per bet type. Does not mention when to use alternatives, but the scope is clearly defined. Lacks explicit 'when not to use' guidance, but the descriptions of edge cases (low confidence, closed markets) imply limitations.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, non-destructive read-only tool. The description adds value by specifying that it queries the 'current routing state on the global BGP table' and returns 'origin ASNs and AS-path lengths', giving behavioral insight into data refresh and output scope beyond the annotations.

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

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

The description is concise—one sentence with embedded examples and uses—covering purpose, return details, and use cases. It is front-loaded with example queries and efficiently communicates key information without redundancy, though it could be slightly more structured for skimmability.

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 existence of an output schema, the description sufficiently explains what the tool does, what it returns, and why to use it. It omits details about pagination, result limits, or global coverage, but these are common expectations and the output schema likely fills gaps. Overall, it is complete for its class.

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

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

Schema description coverage is 100% with a clear description for the 'resource' parameter ('IP, prefix, or ASN'), so baseline is 3. The description reinforces this with examples but does not add new semantic details like input format constraints or allowed ranges. It is adequate but not enhanced 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 returns origin ASNs and AS-path lengths for a given IP, prefix, or ASN from the global BGP table. It provides usage examples ('BGP routes for [prefix]', 'what AS announces [IP]') and explicit use cases (detect BGP hijacks, audit route propagation, find anycast announcers), making the purpose unambiguous and distinguishable from sibling tools like whois or as_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?

The description lists three specific use cases (hijack detection, route audit, anycast identification), which guides when to use the tool. However, it does not mention when not to use it or provide comparisons to alternative sibling tools (e.g., as_overview, prefix_overview), leaving the agent without explicit exclusion criteria.

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

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

The description adds significant context beyond annotations: it explains how it handles off-calendar fiscal years for companies (e.g., AAPL Sep, NVDA Jan), specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), and notes that results are sorted by primary metric. Annotations already declare readOnlyHint and idempotentHint, so no contradiction.

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

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

The description is front-loaded with the tool's purpose and examples, but it is somewhat lengthy. Every sentence provides useful information, so it is not overly verbose for the amount of detail provided.

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 explains what is returned (paired data with citation URIs) and sorting behavior, which compensates for the lack of an output schema. It covers the key aspects an agent needs to invoke the tool correctly.

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

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

Parameter schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of the 'type' enum ('company' pulls financial data, 'drug' pulls adverse-event counts) and providing examples for the 'values' array (tickers/CIKs for companies, drug names). This goes beyond the schema's basic type/format 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 that the tool provides a side-by-side comparison of 2-5 companies or drugs in a single parallel call, with examples of user queries like 'which is bigger' or 'head to head'. It effectively distinguishes itself from sibling tools that handle single entities.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', guiding the agent to use this tool for comparisons instead of multiple entity_profile calls. It does not explicitly state when not to use it, 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 the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses substantial behavioral context: account/paid plan requirements, parallel decomposition into 5,706 tools, output packet structure with gaps[], contradictions[], hop fields and citation_uri fetchability, semantic excerpting behavior, and expected latency. It even clarifies that it never invents findings, which is valuable trust information not available from annotations.

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

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

The description is long but densely informative with no filler; every sentence contributes operational detail. The structure is somewhat sprawling with many parentheticals, but for a tool this complex the length is justified. It front-loads the most critical operational constraints (account requirement, alternative tool) before diving into mechanics.

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

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

Despite having no output schema, the description fully covers the return contract: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers auth, latency, and edge cases like news topics yielding empty gaps. This is complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and the schema already documents depth and question. The description adds meaningful behavioral semantics beyond the schema: depth:'standard' performs gap recovery, depth:'thorough' chases leads, and it clarifies timing implications (15-60s, up to ~90s). This helps an agent choose parameter values based on desired behavior, not just enum names.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' that decomposes questions and routes facets to tools in parallel. It clearly distinguishes itself from ask_pipeworx and open-web search, so an agent can tell exactly what this tool does and what it does not 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 states when to use this tool ('Best for broad/multi-part questions over structured data') and when to prefer alternatives ('For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also provides authentication prerequisites and notes the paid requirement for thorough depth, leaving no ambiguity about 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. Description adds that results include full schemas and are ready to call, no second lookup needed. No contradictions.

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

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

Well-structured with purpose first, then usage, then detail. Slightly verbose but each sentence adds value. Could be tighter but still effective.

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

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

Despite no output schema, description fully explains return value: top-N tools with names, descriptions, and input schemas. Explains its role as discovery tool among many siblings.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions aliases and default limit but does not add significant meaning 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?

Clearly states 'Find tools by describing the data or task' and lists numerous domains. Distinguishes from siblings by being the discovery/search tool among many specific tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate safe, read-only operation. The description adds detail on multi-source fan-out, specific return fields, caveats (patent soft-fail), and fallback behavior, which enriches transparency beyond annotations.

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

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

The description is detailed but front-loaded with intent and examples. Every sentence adds value, though it could be considered slightly verbose given the complexity of the tool. Efficiently 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 and lack of output schema, the description thoroughly explains all return fields, fallback mechanisms, and limitations. It covers what the agent needs to know about the output 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?

Schema coverage is 100% with clear descriptions for type and value. The description adds extra context: examples of tickers, zero-padded CIK format, and explicit note that names are not supported, adding 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 it provides a full cross-source profile of a US public company in one parallel call, with examples of user queries. It distinguishes itself from chaining individual lookups, leaving no ambiguity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' for holistic views, and clarifies when not to use it (if only a name, use resolve_entity first). Good guidance on when to prefer this tool.

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

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

Annotations include destructiveHint: true and idempotentHint: true. Description reinforces deletion and clearing sensitive data. Adds context that it clears 'data the agent saved earlier', but could mention irreversibility. No contradictions.

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

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

Two sentences with no waste. Front-loads the action and provides context immediately.

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?

Complete for a one-parameter tool with no output schema. Describes purpose, usage context, and relationship to siblings.

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 for the single parameter 'key' with description 'Memory key to delete'. Description adds little beyond schema but reinforces that it's a previously stored memory. 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?

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes itself from siblings by mentioning pairing with remember and recall.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with related tools for context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it fetches the page, extracts data, and emits markdown, which aligns with annotations but does not disclose additional traits like rate limits or authentication needs.

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

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

The description is concise, front-loaded with the main purpose, and uses a bullet list for 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?

Given the tool's simplicity (2 params, no output schema) and annotations covering safety, the description is complete enough. It explains inputs, process, and output format ('single text blob'), though it could mention that the output is in markdown.

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 having descriptions. The tool description does not repeat parameter details, but the schema already provides adequate meaning. Thus, the description adds no new semantic value beyond the schema.

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

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

The description clearly states that the tool generates a production-ready llms.txt file for any URL. It specifies the verb 'generate' and the resource 'llms.txt file', and implicitly distinguishes it from siblings like ai_visibility_check by focusing on file generation.

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 lists specific use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. This provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds key behavioral detail: it's registration-based, not GeoIP, and accurate for ownership country. This provides important context beyond annotations.

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

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

Two sentences, no redundancy, front-loaded with example queries. Every word adds value.

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

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

Given the simplicity (1 parameter, output schema exists), description covers purpose, usage, behavior, and parameter basics. Could mention output format but not essential.

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

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

Schema has 100% coverage with description 'IP or prefix'. Description provides examples but doesn't add semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool provides country geolocation from RIR registration data, distinguishing it from GeoIP, and gives example queries. It specifies the resource type (IP or prefix) and the context (compliance/jurisdiction).

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

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

Explicitly tells when to use (compliance/jurisdiction questions where registry truth matters) and when not to use (not for physical location). No sibling confusion as it's unique among 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 read-only and idempotent behavior. The description adds that it returns specific fields and defaults to excluding inactive subscriptions, but no critical behavioral warnings are missed.

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

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

The description is two sentences with no extraneous content, efficiently conveying purpose, returned fields, and usage guidance.

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

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

Despite lacking an output schema, the description lists all returned fields. Combined with full schema coverage and rich annotations, the description is complete for this simple list operation.

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

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

Schema coverage is 100% with a standard description for 'include_inactive'. The tool description does not add additional parameter semantics beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the verb 'list', resource 'subscriptions', and scope 'caller's active'. It also enumerates returned fields, differentiating it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use this tool versus alternatives like subscribing or unsubscribing.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns prefix and ASN, which aligns with annotations. No additional behavioral context (e.g., rate limits) needed for a simple read operation.

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 lean sentences, front-loaded with natural language queries, then formal description and use cases. No filler or redundancy.

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

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

For a simple tool with one parameter, full schema coverage, rich annotations, and an output schema (indicated), the description fully explains purpose, input, output, and usage scenarios without gaps.

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

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

Schema has 100% description coverage for the single 'resource' parameter, including examples. The description echoes that it accepts IPv4/IPv6 addresses but adds no new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description starts with concrete example queries ('What ASN does IP [X] belong to') and clearly states the tool retrieves 'the allocated prefix and originating ASN for an IPv4/IPv6 address'. It lists specific use cases (DDoS source attribution, hosting-provider lookup), distinguishing it from siblings like whois or as_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 says 'Use for' with three usage scenarios. It provides clear context but does not explicitly exclude cases or mention alternatives. However, given straightforward purpose and sibling tools, this is sufficient.

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

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

Annotations provide no positive hints (all false), so description carries full burden. It discloses crucial behaviors: returning a claim_token for later follow-up, rate limiting ('5 per identifier per day'), and that it is free and doesn't count against quota. This is rich behavioral context beyond annotations.

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

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

The description is longer than average but every sentence serves a purpose: purpose, usage types, exclusion, claim_token behavior, rate limit, and quota note. It is front-loaded with the core purpose and structured logically. Slightly verbose but not wasteful.

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 (4 params, nested context object, no output schema), the description fully covers what an agent needs: when to use, what to include, how the claim_token flow works, and limitations. No gaps remain for a feedback 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 claim_token round-trip flow (filing without account returns token, pass it back to read resolution) and giving guidance on message content ('don't paste the end-user's prompt'). This enhances the schema's parameter descriptions.

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

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

The description clearly states the purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource (Pipeworx team) and distinguishes this feedback tool from siblings like ask_pipeworx or discover_tools by focusing on reporting issues/praise about Pipeworx tools specifically.

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: bug, feature/data_gap, praise, and other. It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with the correct server otherwise. This is exemplary usage guidance with explicit 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 concise (3 sentences with parenthetical detail) and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with full annotations and a single parameter, the description is quite complete. It explains what is returned (top tools, packs, call volume) and caching. However, it does not specify the exact output format, which might be a minor gap.

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 'window' has a full enum description in the schema. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the schema's definition.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a given window. It distinguishes itself from siblings by focusing on aggregate trending data, which no other sibling does.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical tools, seeing alignment) and explains the different window options (shorter for hot, longer for steady-state). It does not explicitly mention when not to use, but the use cases are 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 readOnlyHint=true and no destructive behavior. The description adds extensive behavioral context: monotonicity checks, partition-sum checks, semantic anchor for cross-event pairs, partition filter with placeholder fractions, and a fill check that prices against live CLOB depth, including warnings about when not to trade.

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

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

The description is long but well-structured and dense with valuable information. It is front-loaded with the core purpose and follows with clear sections for each mode and technical details. Every sentence adds value, though it could be slightly more concise.

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

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

Despite no output schema, the description explains the response format (opportunities[], partition_check, fill_check) and covers all relevant aspects: usage, parameters, internal behavior, limitations, and fill-check. For a complex tool with no output schema, it is very complete.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it explains that 'event' is a Polymarket event slug (or full URL) and 'topic' is a seed question, provides examples, and describes the behavior of each mode 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and explains when to use each, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit usage instructions: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also mentions when to use polymarket_fill_risk for custom sizing, offering clear alternatives.

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

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

Extensively details behavioral traits beyond annotations: three model families with math details, caching (1h at KV level), Fed bets excluded, edge net of slippage, response structure with diagnostics. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

Front-loaded with purpose but subsequent paragraphs are overly detailed with mathematical formulas and symbols. Could be more concise while retaining key information. Well-structured with sections but length impacts quick consumption by an agent.

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

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

Given 9 parameters, no output schema, and tool complexity, description covers response structure (by_segment, diagnostics), caching, and edge attributes. Provides sufficient context for an agent to understand what to expect.

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

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

100% schema coverage provides baseline 3. Description adds context by grouping tradeable-edge knobs and explaining purpose of min_partition_leg_kelly for partition arbs. Provides value beyond schema but did not need to compensate for coverage gaps.

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?

First sentence clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. Specific verb+resource and distinguishes from siblings like polymarket_arbitrage by focusing on data disagreement.

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 built for 'what should I bet on today' and agents discovering opportunities without paging. Provides clear context but lacks explicit when-not-to-use or direct comparison to sibling tools beyond implied differentiation.

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

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

The description details the response structure (tracked, expired, snapshot_dates) and explains each field's meaning, including edge sign conventions and decay computation. It also discloses limits (60-day TTL, cache-miss snapshots). Annotations already indicate read-only and idempotent behavior, and the description adds no contradiction.

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

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

The description is thorough yet concise, front-loading the core purpose and then efficiently detailing the response structure and limits. Every sentence provides necessary 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 the absence of an output schema, the description fully explains the return values (tracked, expired, snapshot_dates) and their subfields. It covers edge cases (e.g., negative edge values) and temporal constraints (60-day TTL). The tool is complex but the description provides complete 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% with descriptions for both parameters. The description adds context beyond the schema by explaining default values, clamping behavior, and the meaning of window families. However, much of the parameter info is already in the schema, so the added value is moderate.

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, answering a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis and decay trends.

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

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

The description implicitly guides usage by explaining what the tool answers ('how long has this edge existed and is it shrinking?'), but it doesn't explicitly state when to use this tool versus alternatives like polymarket_edges. It provides clear context but lacks explicit when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, etc. The description adds details like walking the ladder, returning specific metrics, and warns of risks like partial fills converting arbs into directional positions, consistent with read-only 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?

Well-structured with uppercase headings (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded purpose. Slightly verbose but each sentence adds necessary information for correct invocation.

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 explains return values for both modes in detail. Covers all necessary aspects: modes, parameters, defaults, safety considerations, and why it's important. Complete for its 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% (all 4 parameters have descriptions). The description adds further context: explains mode differences, default side logic, size_usd interpretation, and clamp range, adding 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 it performs a realizable-vs-theoretical edge check against live order-book depth, distinguishes between single-market and basket modes, and lists returned fields. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs the agent to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500, and warns about partial fills leading to unhedged directional positions, providing clear when-to-use and why.

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, and the description goes far beyond them by disclosing compatibility_warning, compatibility_codes, skipped pair categories, temporal_alignment, and per-leg flags. It even explains the rule that unknown metric_type/match_subtype legs are never paired and that warnings may be non-empty even with matched_pairs>0. No contradiction exists between description and 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 and dense, but each block earns its place: core purpose, modes, response shape, safety fields, code meanings, and caveats. It is front-loaded with the main definition and mode guidance before edge-case details. Slightly overwhelming in raw size, but this is a complex tool with no output schema, so the length is justified.

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

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

With no output schema, the description must explain return values and edge cases, and it does so thoroughly: response layout, top_spreads_pp, compatibility codes, skipped counters, temporal alignment, and the unclassified-leg policy. Concrete ticker/slug examples and code names leave little ambiguity. Nothing an agent needs to select or invoke this tool correctly 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?

The input schema has 100% coverage with descriptions for all three parameters, including the topic enum list and override behavior. The description adds meaning by explaining how the parameters interact (topic mode auto-fetches, explicit ticker/slug overrides the mapped side) and by clarifying that topic mode often yields compatibility warnings. This adds real value beyond what the schema alone provides.

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

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

The description states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by naming both venues and the spread concept. The scope is precise and immediately understandable.

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 details two modes — pre-mapped topic shortcuts and explicit ticker/slug pairings — and when to use each. It also warns that most pre-mapped topics return compatibility warnings and that 'pre-mapped ≠ tradeable', giving clear when-not-to-trust guidance. It does not name sibling alternatives for related comparisons, so it misses the 'alternatives' criterion, but the context is otherwise strong.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context about what the summary includes (BGP announcements, origin ASes, allocation history) beyond what annotations provide. No behavioral downsides are omitted.

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

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

Two concise lines with examples and purpose, no wasted words. Front-loaded with common query patterns.

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

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

For a simple one-parameter tool with an output schema, the description fully covers the tool's purpose, data returned, and usage guidance. No gaps.

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

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

Schema coverage is 100% for a single parameter with a clear description. The description reinforces the parameter meaning with example formats '[CIDR]' and '[X/Y]', adding slight value over the schema alone.

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

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

The description clearly states that the tool provides a comprehensive summary for an IP prefix including BGP announcements, origin ASes, and allocation history. It uses clear verb phrases like 'Prefix overview' and 'comprehensive summary'. It distinguishes itself from siblings by noting it replaces chaining bgp_state and whois.

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 to understand a whole IP block at once instead of chaining bgp_state + whois', providing clear when-to-use guidance and naming 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=true and destructiveHint=false, so the description adds value by noting scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the pairing with remember and forget. 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?

Three sentences, front-loaded with the primary action, and each sentence adds distinct value: function, usage examples, scoping and pairing. No wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers purpose, usage, scoping, and pairing. It could explicitly state the return format when listing keys, but overall it's fairly complete.

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

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

Parameter schema coverage is 100% and the schema already explains the optionality. The description adds context about the key's purpose and pairing with remember/forget, reinforcing the behavior 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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It provides a specific verb and resource, and explicitly distinguishes from sibling tools like 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 says 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It gives concrete examples (ticker, address, research notes) and mentions scoping. It lacks explicit when-not-to-use but implicitly contrasts with remember/forget.

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

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

Annotations already declare readOnly and idempotent hints. Description adds key behavior: setting mark_read:true flags events as read, affecting subsequent calls. No contradiction.

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

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

5 sentences, each adding value. Front-loaded with purpose, then return fields, then filter options, then behavior, then context. No fluff.

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

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

Covers all 5 parameters adequately. No output schema, but description states returned fields. Sibling tools are many but not conflicting. Adequate for a read-only polling 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%, baseline 3. Description adds behavioral detail for 'mark_read' and clarifies filtering by type/since, beyond schema descriptions.

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

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

Specific verb 'Pull' with clear resource 'fired events from your subscription feed'. Describes returned fields and distinguishes from GET endpoint at registry.pipeworx.io/alerts.json.

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

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

Provides clear context for polling use and alternative for scripts/dashboards. Lacks explicit when-not-to-use compared to siblings like 'list_subscriptions' or 'subscribe'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: fan-out to three sources (SEC EDGAR, GDELT→GNews fallback, USPTO), handling of rate limits/5xx errors, USPTO sunset info, and return structure (changes grouped by source + citation URIs). No contradiction with annotations.

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

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

The description is compact yet comprehensive, with every sentence providing unique value. It front-loads usage examples and clearly separates purpose, sources, parameters, and alternatives. No redundant or filler content.

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

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

For a tool with 3 parameters (all described), no output schema, and rich annotations, the description fully covers the tool's domain: data sources, fallback logic, return structure, and relationship to sibling tool. An agent can confidently invoke it.

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

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

Schema coverage is 100% but description adds value beyond: clarifies 'since' accepts ISO dates or relative shorthand (7d, 30d, 3m, 1y), suggests '30d' for monitoring, and notes that 'type' currently only supports 'company'. This enhances usability.

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 specific verb-resource ('change feed for a company') and includes example queries like 'What's new with X' and 'updates on Acme'. It explicitly distinguishes from the sibling tool entity_profile, making the purpose unmistakable.

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

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

The description clearly states when to use this tool vs. entity_profile ('Use entity_profile instead when you want the static profile'). It also provides guidance on the 'since' parameter with suggested defaults ('Use 30d or 1m for typical monitoring'), though it lacks explicit exclusions for non-entity queries.

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

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

Annotations provide idempotentHint=true and readOnlyHint=false. The description adds behavioral details: key-value storage scoped by identifier, persistence differences between authenticated users and anonymous sessions (24 hours). No contradictions.

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

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

Four concise sentences, front-loaded with purpose. Every sentence adds unique information without redundancy. No fluff.

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

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

Given the simple 2-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage, storage behavior, persistence, and cues for related tools. Fully adequate.

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

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

Schema has 100% coverage with descriptions for 'key' and 'value'. The description adds value by providing example keys (e.g., 'subject_property', 'target_ticker'), but does not add significant additional semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides concrete examples like 'a resolved ticker, a target address, a user preference'. This verb-resource combination distinguishes it from siblings like 'recall' and 'forget'.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also pairs with 'recall' and 'forget', guiding the agent on complementary 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behaviors: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers under `unresolved`, and the cascading through multiple lookup endpoints. It also explains the cross-source identity spine and how ISINs resolve to legal entities, adding context not available from annotations alone.

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 quite long and dense, but it is front-loaded with example queries and a clear purpose statement. Each sentence adds functional detail (e.g., source labeling, fallback behavior, cross-source mapping), so despite its length, it is efficiently structured. It could be trimmed slightly, but no sentence is wasted.

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 compensates by detailing what is returned: canonical identifiers with source labels, explicit mention of unresolved identifiers, and the graceful degradation behavior. It covers both supported types and edge cases like non-US issuers via ISIN-to-LEI mapping, making it comprehensive enough for an agent to know what to expect.

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

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

Although the input schema already describes both parameters, the description adds significant semantics: for `company` it accepts ticker, CIK, ISIN, or name; for `drug` it accepts brand or generic. It also clarifies that an ISIN resolves to the legal entity issuing the security, which is not obvious from the schema. This far exceeds the baseline for high schema coverage.

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

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

The description opens with concrete user queries and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists supported types (company, drug) and distinguishes itself as the first step in a lookup workflow, clearly separating it from siblings like entity_profile or compare_entities.

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

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

The instruction 'Use FIRST whenever you have a name but need an ID' is a clear, explicit trigger for when to invoke this tool. It also notes that it 'replaces 2-3 manual lookups,' reinforcing its role as a preliminary resolution step, while implicitly distinguishing it from tools that consume already-resolved IDs.

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, destructiveHint. Description adds that it internally calls ai_visibility_check for each entity, ranks by score, and surfaces most/least recognized. Provides output details (score, confidence, signal density). No contradiction.

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

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

Two sentences, front-loaded with purpose. Every sentence contributes: purpose, mechanism, use case, output format. 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 no output schema and 100% schema coverage, description adequately covers purpose, behavior, parameters, and output format (ranked list with score, confidence, signal density). Lacks error handling or limitations, but sufficient for selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains 'entities' first is the subject for narrative, 'context' as shared disambiguation, and 'models' are implicitly covered. Adds value beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities. It uses specific verb 'Compare' and resource 'AI visibility', distinguishing it from sibling 'ai_visibility_check' which probes a single entity.

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

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

Provides explicit use case: 'competitive AI-marketing audits' and example question. Implies not for single-entity checks, which are handled by 'ai_visibility_check'. Does not explicitly state when to avoid, but context is clear.

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

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

The description goes beyond the read-only and idempotent annotations by detailing graceful degradation: bundlephobia's first measurement may take 5-30s and sources_failed lists timeouts. It also describes the return structure (summary, advisories, links, alternative versions), providing full 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 efficiently covers usage, behavior, and limitations. While lengthy, every sentence provides necessary context without redundancy. The structure is logical and easy to parse.

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

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

Given the tool's complexity (composite check, multiple data sources, partial failures) and the absence of an output schema, the description is remarkably complete. It explains inputs, outputs, behavior, edge cases, and graceful degradation, leaving no critical gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages are accepted for 'package' and that 'version' defaults to the latest when omitted, enriching the schema's minimal 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 composite purpose ('should I add this npm package to my project' check) and lists the data sources (deps.dev and bundlephobia). It distinguishes from siblings by specifying the NPM ecosystem scope and referencing alternative tools for other ecosystems.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also clarifies limitations ('NPM ecosystem only in v1') and directs to alternative methods for other package managers.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds details beyond: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation flag, and offset verification. No contradiction.

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

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

Two sentences packed with all necessary information, front-loaded with purpose, no redundancy.

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

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

Given no output schema, description explains return value (passages with offsets and similarity scores) and technical details (embeddings, chunking). All parameters covered, use case clear.

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 100%. Description reinforces text and query parameters with examples (e.g., 'supply-chain risk') and clarifies limit defaults. Adds marginal value beyond schema, hence 4.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying it returns top-N passages with character offsets and similarity scores. It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing and use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Also implies when not to use other 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?

Description adds significant behavioral details beyond annotations: auth requirement, delivery channel constraints, SMS verification, webhook signing, rate limits. However, idempotentHint=true annotation may conflict with the implication that each call creates a new subscription.

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 dense but well-organized with examples and colons for readability. Could be more scannable with bullet points, but 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?

Covers purpose, auth, type options, delivery behavior, and return value. Lacks error handling but is adequate for a creation tool with no output schema.

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

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

Schema coverage is 100% and description enriches every parameter: type with supported values, params with detailed type-specific filters, delivery with usage constraints and examples.

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, specifies the returned subscription ID, and distinguishes it from siblings 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?

Provides context on when to use (create subscriptions), required auth (Pipeworx OAuth), and type-specific examples, but does not explicitly state when not to use or compare to 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 mark the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the returned content (categorized questions with tool+argument shapes) beyond what annotations provide, without contradicting them.

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

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

The description is front-loaded with the purpose and structured effectively, but it is slightly verbose with the full list of categories. Each sentence serves a purpose, though minor trimming could improve conciseness.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully explains what it returns (categorized example questions with tool shapes) and how to use it (with or without topic). It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with a brief description of the parameter. The description adds meaning by listing possible values (e.g., finance, pharma) and explaining the effect (full spread vs. focused topic), going beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs (returns, use first) and distinguishes from siblings like discover_tools by positioning itself as the initial go-to tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions optional topic filtering. It provides clear context for when to use but does not explicitly state when not to use, e.g., after initial discovery.

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

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

Adds behavioral context beyond annotations: explains that the row is deactivated, not deleted, and that historical events remain available. Annotations provide idempotent hint, destructive hint false, and description aligns. No contradictions.

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

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

Two sentences that front-load the core action and then provide important behavioral details. No wasteful language.

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 required parameter, no output schema), the description adequately covers purpose, ownership constraint, and the deactivation behavior. Complements the existing annotations and schema.

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

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

Schema provides 100% coverage with a description for the 'id' parameter. The description does not add additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', which is a specific verb-resource combination. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when the tool can be used. However, does not explicitly state when not to use it or list 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?

The description goes well beyond the annotations by disclosing the two distinct execution paths (SEC EDGAR/ XBRL for financial claims vs grounded pipeline for others), the exact verdict enumerations, the presence of pipeworx:// citations and reasoning, and the behavioral distinction between could_not_verify and unsupported. It also explains error semantics for could_not_verify. Annotations already cover read-only/idempotent, so this adds substantial operational 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 longer than typical but efficiently packed with necessary information: opening examples, routing logic, output schema, and caller-critical caveats. The structure front-loads the purpose, then dives into behavior. A slight deduction for the opening phrase list which could be trimmed to fewer examples, but it's not wasteful overall.

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

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

Despite having no output schema, the description enumerates every possible verdict, describes the return payload (evidence, citation, reasoning), and explains error/unsupported semantics. It also clarifies the internal pipeline enough for an agent to set expectations. For a tool with only two parameters and no nested objects, 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?

The schema descriptions cover 100% of parameters, so the baseline is 3. The tool description adds value by explaining how claim text maps to routing (financial vs other) and clarifies the tolerance behavior indirectly via the verdict 'approximately_correct' and the note about 'exact percent-delta math.' It does not provide new syntax details beyond the schema but enriches the meaning of the claim parameter with diverse examples and classification.

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

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

The description clearly states the verb (validate/verify), resource (natural-language claims), and scope (against authoritative sources). It starts with concrete example phrasings, then distinguishes between company-financial claims (SEC EDGAR/ XBRL fast path) and any other factual claim (grounded pipeline). It also explicitly notes it replaces 4–6 sequential calls, distinguishing it from generic Q&A tools like ask_pipeworx or deep_research.

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

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

It states explicitly: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives criteria for when to use the fast path vs the grounded pipeline, and provides critical guidance on how to interpret could_not_verify and unsupported verdicts. This is strong when-to-use guidance with no competing alternative mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds behavioral context by specifying that it queries all five RIRs and returns aggregated data, which goes beyond the annotations. No contradictions.

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

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

The description is concise and well-structured: it starts with the core purpose in natural language, then provides the technical detail, and ends with use cases. Every sentence adds value without redundancy. Ideal length for quick comprehension.

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 one simple parameter, an output schema exists, and annotations cover safety, the description is complete. It explains what the tool does, what inputs it accepts (with examples), what it returns, and when to use it. Nothing 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% and the schema description explains the parameter. The tool description adds concrete examples (e.g., '8.8.8.8', '8.8.8.0/24', 'AS15169'), which help the agent understand valid formats beyond the generic schema description. This adds meaningful 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 it performs whois lookup for IP/ASN/prefix using all five RIRs, and explicitly mentions the returned fields (registrant org, country, abuse contacts, allocation date). It also provides alternative natural language queries. While not explicitly differentiating from siblings, the specificity of 'aggregated whois data' sets it apart from related tools like geoloc or 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?

The description explicitly lists use cases: 'Use for IP ownership, abuse-response, network forensics.' This provides clear context for when to use the tool. However, it does not explicitly state when not to use it or recommend alternative tools, such as `abuse_contact` for only abuse contacts or `geoloc` for geolocation.

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