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?

The description adds meaningful behavioral detail beyond the annotations: it routes questions across thousands of tools, fills arguments automatically, and returns structured answers with stable citation URIs. Annotations already cover read-only/idempotent safety, so the description's added routing and citation behavior is sufficient though it does not discuss failure modes or limitations.

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 front-loads the key directive and packs in useful examples and trigger phrases. The repetition of 'START HERE' and the broad domain list is somewhat redundant, but each part contributes to the agent's ability to recognize when to use it.

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 broad, open-ended question-routing tool with no output schema, the description covers the essential invocation context: when to use it, what kind of inputs work, and what kind of output to expect (structured answer with citation URIs). It could be more complete about output formatting or failure behavior, but the core usage scenario is well covered.

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 that all parameters are aliases for a single natural-language question. The description reinforces natural-language usage with examples but adds little semantic value beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes natural-language questions about factual/current data to appropriate sources and returns a structured answer with citation URIs. It distinguishes itself from web search, but does not explicitly differentiate from sibling tools like ask_pipeworx_beta, ask_pipeworx_grounded, or deep_research, so it falls short of a 5.

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

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

The description gives strong, explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH', trigger phrases like 'look up' and 'get the latest', and examples. It clearly positions the tool as the default for factual questions, but it does not provide when-not-to-use guidance or mention sibling alternatives, so it stops short of full routing clarity.

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

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

Beyond the read-only, idempotent, non-destructive annotations, the description discloses the live experimental behavior: candidate routing improvements may be active, none is active right now, and results are compared with the stable router. This gives the agent an accurate picture of potential variability.

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 minimal but every sentence contributes useful context: beta status, current equivalence, usage recommendation, and experimental comparison behavior. Key facts are front-loaded, though a little redundancy exists around 'currently matches ask_pipeworx exactly'.

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 that takes only a natural-language question, the description covers the essential invocation context: same arguments, same response shape, current behavior, and experimental nature. Since the sibling ask_pipeworx exists as a reference, the agent has everything needed to call this tool correctly.

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

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

Schema coverage is 100% and every parameter is described as an alias for the single 'question' parameter. The description only adds 'same arguments' by referencing ask_pipeworx, which is consistent but does not add meaningful 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 identifies this as a beta universal router with the same tools, arguments, and response shape as ask_pipeworx, while explicitly differentiating it as the experimental routing edge. It states what the tool does and how it relates to its stable sibling.

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

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

It provides explicit usage guidance: use it exactly like ask_pipeworx when you want the newest routing. It also clarifies that it is a full working router, not a fallback. It does not enumerate exclusions or compare against ask_pipeworx_grounded, but the guidance is otherwise 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 mark it read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: it only extracts from tool results, returns explicit success and refusal shapes with enumerated refusal reasons, and discloses the extra LLM call cost. This goes well beyond what the annotations provide and contains 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 longer than one sentence, but every sentence earns its place: core behavior, output shape, refusal contract, usage guidance, and cost trade-off. It is front-loaded with the most important property ('Hallucination-resistant answer mode for high-stakes reads') and contains 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?

With no output schema, the description fully explains the return contract on both success and refusal, lists refusal reasons, states when the tool should be chosen, and gives the cost comparison against the sibling. Nothing an agent needs to safely invoke and interpret this tool 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 description coverage is 100%, so the schema already fully documents the single question parameter and its aliases. The description does not add parameter-level detail, but because the schema handles it, the baseline of 3 is appropriate.

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

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

Description states a specific verb ('EXTRACTS the answer using ONLY what the tool result contains') and resource (Pipeworx across 5,798 tools/1,517 sources), and distinguishes itself from ask_pipeworx as the hallucination-resistant, grounded answer mode. The contrast with siblings is sharp and immediately actionable.

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

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

Explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', including concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also names the alternative and the trade-off: 'prefer ask_pipeworx for casual lookups' because this costs one extra LLM call.

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

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

Annotations already 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?

Annotations already mark this as read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral detail: account requirements, parallel execution, findings-packet structure, gaps[] never being invented, hop/citation_uri fetchability semantics, contradictions[] on standard/thorough, semantic excerpting of large records, and expected latency. 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 opening is front-loaded and useful, but the description becomes seriously bloated by a long repeated 'Wait, the text after...' fragment and redundant restatement of material already in the schema. The mid-section is noisy and poorly structured, which hurts an agent's ability to quickly parse the most important 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?

For a complex tool with no output schema, the description is very complete: it explains the data universe, decomposition and parallel routing, the contents of the findings packet, gap reporting, citation_uri fetchability, contradictions, excerpting behavior, auth requirements, and latency. An agent has enough to invoke it correctly and interpret results.

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

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

The schema already covers both parameters 100%, so the baseline is 3. The description adds useful operational context beyond the schema, such as the purpose of the question parameter (broad/multi-part is fine), the timing expectations, and the behavioral differences between depth tiers. This exceeds the baseline but doesn't add dramatically new parameter-level detail.

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

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

The description clearly identifies the tool as a grounded multi-source research tool over Pipeworx's structured data sources, explaining that it decomposes questions and routes facets to tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, making the purpose unambiguous.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, and when-not-to-use: single lookups should go to ask_pipeworx, and unsigned-in users should use ask_pipeworx. It also notes that thorough depth requires a paid plan. This is model-level usage guidance.

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

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

Annotations already declare readOnlyHint=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 already mark the tool read-only, idempotent, and non-destructive, and the description adds rich behavioral detail: cross-source fan-out, USPTO patent soft-failure, FDA empty-section expectations, sources_used/sources_failed, and resolved_from/resolved_to behavior. There is no contradiction with the annotations.

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

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

The description is long but dense, with trigger examples and the 'ALWAYS PREFER' guidance front-loaded before source/output details. Some sentences repeat schema content, but the length is justified for a multi-source tool with this many behavior notes.

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

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

With no output schema, the description compensates thoroughly by enumerating return sections, source lists, expected empty results, soft-failure behavior, and private-company resolution. It gives an agent enough context to invoke the tool correctly and interpret results plausibly.

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

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

Schema description coverage is 100% and the schema already documents type/value semantics, including ticker/CIK/name resolution and the interchangeability of 'company' and 'ticker'. The description mostly restates these input facts, adding output behavior like resolved:false rather than new parameter meaning, so the baseline 3 applies.

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 anchors the tool with natural-language triggers ('Tell me about X', 'research Acme', 'brief me on Tesla') and an explicit definition: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact resource and scope, and it is clearly distinguishable from the single-pack SEC/XBRL/news lookups it is meant to replace.

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

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

It explicitly instructs agents to 'ALWAYS PREFER' this tool over chaining single-pack lookups when the user asks for a holistic view. It also covers edge cases like private companies returning resolved:false, so the agent knows when and how the tool applies.

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?

Beyond the read-only and idempotent annotations, the description discloses the token-overlap matching mechanism, compatibility warning codes, fee treatment (gross, not net), exclusion of unknown legs, and interpretation caveats for temporal alignment. This is substantial behavioral context that annotations and schema alone do not provide.

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

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

The description is long but well structured: it front-loads purpose and modes, then organizes response, safety fields, and fee caveats. Some temporal-alignment caveats are repeated, but the density is justified given the tool's complexity and warning-rich output.

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?

Even without an output schema, the description explains the essential response fields, safety flags, compatibility codes, skipped-leg counters, and the gross-vs-net fee limitation. An agent has enough information to invoke both modes and interpret returned warnings 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 covers all three parameters, so the baseline is 3. The description adds meaningful semantics by explaining that topic is a pre-mapped shortcut, that explicit parameters override the mapped side, and that both modes run the identical matcher. This exceeds schema-level documentation without being redundant.

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

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

The description clearly states that this tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question and outlines two modes. It is specific about verb and resource. However, it does not explicitly distinguish itself from closely related sibling tools such as polymarket_arbitrage.

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

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

The description explicitly documents the two modes and when to use topic shortcuts versus explicit ticker/slug pairings. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped does not mean tradeable. It does not, however, name sibling alternatives or provide clear when-not-to-use guidance.

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

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

Annotations already indicate 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, but the description adds substantial behavioral context: it cascades through multiple lookup endpoints internally, degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR still returns), returns `figi_candidates` when ambiguous without asserting a result, and lists unresolved identifiers explicitly under `unresolved`. This goes well beyond the annotations and gives the agent a clear model of what happens during execution. No contradiction with annotations exists.

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 (several paragraphs) but extremely front-loaded: the first sentence delivers the core purpose and examples, and the 'Use FIRST' instruction appears early. It then systematically covers supported types, edge cases, and degradation. While every sentence adds value, the length could be slightly trimmed without loss. The structure is logical (overview → types → behavior → fallback), and it avoids redundancy, but it is not concise in the strict sense. Given the tool's complexity, this is appropriately sized, though it could be tightened.

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 return behavior: it mentions `figi_candidates`, `unresolved` for failures, and labels each identifier with its source. It explains handling of ISINs, non-US issuers, and non-equity instruments. It also notes graceful degradation and that it replaces multiple manual lookups. For a tool with two parameters and considerable complexity, nothing essential is missing; the 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?

The schema already provides descriptions for both parameters (coverage 100%), so a baseline of 3 applies. However, the description enriches parameter meaning significantly: for `value`, it clarifies that for a bond you must pass the ISSUER exactly as printed, never the full noun phrase, and explains the reason. It also specifies that for `type='company'` the input can be ticker, CIK, ISIN, or name, and for `type='drug'` a brand or generic name. This additional guidance goes beyond the schema's plain descriptions and directly influences correct invocation.

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

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

The description opens with concrete natural-language examples ('What's the ticker for…') that make the tool's purpose unmistakable: it maps a spoken name to official identifiers (CIK, ticker, LEI, RxCUI). It explicitly states it is the tool to use 'whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile that likely operate on existing IDs. The purpose is specific, actionable, and clearly separated from other tools.

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

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

The description gives a direct directive: 'Use FIRST whenever you have a name but need an ID.' It then specifies exactly what inputs are accepted per type and even warns against passing the full noun phrase for bonds, explaining the reason (FIGI lookup matches instrument names). It covers when to use it (name→ID) and implicitly when not (when you already have an ID), and it mentions that it replaces 2-3 manual lookups, indicating efficiency. No other tool is named, but the guidance is unambiguous.

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.