dns

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

Annotations already establish read-only/idempotent/non-destructive behavior; the description adds genuinely useful context beyond that: the default free model (Workers AI Llama-3.3-70b), the cost implication of using a BYO Anthropic key, and the exact return format (per-model {score, confidence, signals, raw_response} + combined view). This enriches the agent's understanding of tool behavior without over-explaining.

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 tight and front-loaded: core action first, then default model, key option, return format, and use cases. Every sentence serves a purpose—no filler or repetition of schema details. It remains readable while packing essential information.

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

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

Despite having no output schema, the description covers the return shape, default vs optional behavior, cost implications, and typical use cases. With safe annotations already declared, the description provides sufficient context for an agent to decide when and how to invoke the tool, including handling the optional Anthropic key.

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 baseline is 3. The description adds operational nuance: it explains that `_apiKey` is only needed when 'anthropic' is in models, that it is passed directly to api.anthropic.com, and that users pay Anthropic directly. This goes beyond raw schema definitions and helps the agent understand parameter relationships.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know...' and clarifies the output (visibility 0-100 per model). It distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on per-model visibility scoring rather than generic Q&A or competitor scanning.

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

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

The description provides a clear 'Useful for' section listing relevant use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), giving strong contextual guidance. However, it does not explicitly mention when to avoid this tool or name an alternative tool for those exclusions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral detail: it routes to one of 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not mention latency or failure modes, but that is minor given the annotation coverage.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and every section serves selection or invocation: scope, examples, and sibling routing. It is slightly verbose, but the density of useful guidance justifies the length.

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

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

The tool is complex, and the description covers when to use it, what it returns, examples, and when to route to alternatives. There is no output schema, but the description explicitly mentions the structured answer and citation URIs. It does not mention ask_pipeworx_beta, but 'START HERE for most questions' makes the default choice 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 description coverage is 100%, so the baseline is 3 and the schema already documents the question parameter and its aliases. The description adds example queries but does not elaborate on parameter syntax or constraints beyond what the schema provides. This is adequate but not a differentiator.

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

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

The description states a specific purpose: route factual questions to the right tool among thousands of verified sources and return a structured answer with pipeworx:// citations. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the agent's selection unambiguous.

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

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

The description tells the agent to prefer this tool over web search and provides explicit triggers ('what is', 'look up', 'find', 'get the latest', etc.) plus concrete examples. It also gives explicit when-not-to-use guidance: use deep_research for deep multi-step reasoning and ask_pipeworx_grounded for hallucination-resistant single answers.

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 readOnly/openWorld/idempotent annotations, the description discloses that routing improvements are enabled live during tests, that no candidate is currently active, and that the tool is a full working router rather than a fallback. This gives the agent accurate expectations that behavior may change over time while remaining non-destructive.

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 is substantive, covering current beta state, parity with ask_pipeworx, and usage intent. It is front-loaded with the tool's identity and remains structured enough for an agent to parse quickly.

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 question-routing tool with no output schema, the description covers current state, parity, and usage, and references ask_pipeworx for the exact argument and response contract. It could be more self-contained by describing the response shape directly, but the comparison is workable given sibling access.

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

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

Schema coverage is 100%, with all aliases documented in the schema, so the description does not need to repeat parameter details. It only adds that arguments are identical to ask_pipeworx, which is parity information rather than new semantic meaning, so 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?

The description clearly identifies the tool as the beta version of ask_pipeworx, explicitly calling it an identical universal router with the same tool set, arguments, and response shape. It distinguishes this variant from the stable ask_pipeworx as the experimental edge, so an agent can tell them apart.

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 to use it exactly like ask_pipeworx when the newest routing behavior is desired, and it references the stable router for comparison. It conveys the experimental context clearly, though it does not explicitly enumerate when-not-to-use conditions or all alternative tools.

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

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

The description details the exact return shape, including success fields and explicit refusal reasons such as 'not_in_source' and 'data_truncated'. This goes well beyond the annotations, which already mark the tool as read-only, idempotent, and non-destructive. No contradiction 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 dense but every sentence earns its place: what the tool does, what it returns, when to use it, and when not to. It front-loads the core behavior and keeps the trade-off guidance at the end without 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 tool with no output schema, the description fully compensates by specifying the response envelope, refusal reasons, fallback behavior, and usage boundary. Combined with the annotations and schema, an agent has everything needed to invoke and interpret 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 description coverage is 100%, and the schema already documents the single question parameter with all its aliases. The tool description adds no extra parameter-level meaning, so it appropriately stays at the baseline 3.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with an explicit verb and resource. It distinguishes itself from ask_pipeworx by explaining the grounded extraction mechanism, so an agent can tell them apart without opening schemas.

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

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

Provides explicit guidance on when to use this tool: whenever an answer will be quoted, cited, or acted on, and facts must not be invented. It also names the alternative (ask_pipeworx) and states the cost trade-off ('costs one extra LLM call'), recommending the cheaper option for casual lookups.

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

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

The description discloses extensive behavioral traits beyond annotations: resolver confidence levels, fan-out logic, response shapes, safety short-circuits, market closed/inactive status, wide-spread illiquidity, and resolution-rule risks. It adds rich context to the readOnly/idempotent/openWorld annotations.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and dense, relevant information. Every sentence earns its place, though the length is substantial. It is not minimal but remains appropriately organized for the tool's complexity.

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

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

Given no output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence, result.market_match_confidence, result.parent_event) and edge cases (closed markets, low-confidence matches, news fallback). It covers all necessary context for safe and correct 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 description coverage is 100%, so the baseline is 3. The description adds examples of market input formats but does not materially extend the schema's parameter descriptions. Depth and include_raw are thoroughly documented in the schema, so the description provides no significant additional parameter semantics.

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

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

The description clearly states the tool's function ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') with a specific verb and resource. It distinguishes itself from sibling tools by detailing the resolver, classifier, and fan-out behavior, making its purpose unambiguous.

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

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

Explicitly specifies use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides guidance on quick vs thorough depth, and warns about low-confidence matches and closed markets, giving clear context for when to use or avoid the tool.

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

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

The description discloses substantial behavioral details beyond annotations: it makes a parallel call rather than multiple calls, pulls from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years, sorts results by primary metric, and returns citation URIs per entity. This equips the agent with expectations about performance, data sources, and output structure—far beyond the readOnly/idempotent hints.

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

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

The description is dense but every sentence serves a purpose: usage triggers, tool preference rule, data sources, sort behavior, return format, and efficiency claim. It is front-loaded with the most important info (what it does) and wastes no words. Structure is scannable and actionable.

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

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

For a tool with no output schema and two entity types, the description covers the essentials: scope (2–5 entities), data sources per type, handling of fiscal year edge cases, sorting by primary metric, and citation URIs. It also communicates the key benefit of replacing many lookups, giving the agent full context for 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?

Although the schema already documents both parameters (type enum and values array), the description adds valuable semantic context: type="company" maps to 10-K financials, type="drug" maps to FAERS/trial data, and values format examples are given (tickers for company, names for drug). This enriches the bare schema with real-world meaning.

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

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

The description opens with concrete natural-language query patterns ("Compare X and Y", "which is bigger") and explicitly defines the action: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It clearly distinguishes itself from sibling tools like entity_profile by framing sequential single-pack lookups as inferior for this 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?

It states an explicit rule: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." Type-specific behavior for company vs drug is explained, and the mention of "Replaces 8–15 sequential lookups" reinforces when this tool is appropriate. This gives the agent clear decision 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?

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description's behavioral disclosures are consistent and richly detailed: account requirement, parallel decomposition into 5,798 tools, gap recovery hops, contradiction scans, fetchable citation_uri, semantic excerpting, and latency expectations (15-60s, up to ~90s for thorough). This far exceeds annotation coverage.

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 information-dense and every sentence earns its place: account requirement, routing, decomposition, output contents, gaps, depth tiers, citation fetchability, excerpting, latency. Front-loading is strong with the ACCOUNT REQUIRED warning and the ask_pipeworx alternative first. The only minor deduction is the parenthetical-heavy style that slows parsing.

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 2 parameters, no output schema, and heavy annotations, the description fully covers what an agent needs: prerequisites, timing, depth semantics, citation resolution, gap-handling, and comparison to siblings. Nothing essential is missing for correct invocation and expectation-setting.

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 covers both parameters. The description adds useful behavioral nuance to depth ('standard adds a gap-recovery hop', 'thorough=6... full iterative hop'), but it doesn't add new semantic meaning beyond the schema's already-detailed enum descriptions. Baseline 3 plus the depth behavior context earns a 4.

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

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

The description uses specific verbs and resources: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call — this is NOT open-web search.' It clearly distinguishes deep_research from open-web search and from sibling ask_pipeworx. The wording names concrete source categories and the output packet, making the tool's 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 explicitly states when to use deep_research ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'). It also names ask_pipeworx as the fallback for unsigned users and differentiates from open-web search. This is strong routing 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 it read-only, idempotent, and non-destructive. The description adds return-format behavior: top-N tools with full schemas and curated examples, ready to call directly with no second lookup. This is supplemental behavioral transparency beyond annotations.

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

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

The description is well-structured and front-loaded with the core purpose. The domain list is somewhat lengthy but serves as useful search examples. Each sentence contributes, though a few items in the list could be trimmed.

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 tool has no output schema, so the description's explanation of return format is essential and provided. It covers purpose, usage timing, and return capabilities. Combined with rich annotations, the description is fully adequate for agent invocation.

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

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

Schema coverage is 100%, with detailed descriptions for query, limit, and aliases. The description's mention of 'top-N' and 'describing the data or task' reinforces existing schema info but does not substantially add new parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: finding tools by describing data or task. It specifies the verb (find), resource (tools), and usage context (browse/search/discover), distinguishing it from sibling tools that perform the actual data tasks.

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 says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST' when many tools are available. This provides clear context and implies a when-not-to-use (when you already know the specific tool).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds that results include TTLs and data values, which is useful but does not disclose potential rate limits or error behavior. No contradiction; benefits slightly from annotation coverage.

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

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

Two sentences, front-loaded with the action and scope, followed by examples and return fields. No filler; every sentence earns its place.

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

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

With an output schema present and annotations covering safety/idempotence, the description provides sufficient detail for a simple lookup tool. It explains purpose, record types, and return values. While it could mention the sibling 'dns_lookup_all', that is not necessary for basic usage.

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

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

Schema covers 100% of parameters with detailed descriptions including the default value for 'type'. The description's record type examples (e.g., 'A', 'MX') are already present in the schema, so it adds no meaningful beyond-schema semantics.

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

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

Description starts with 'Look up a specific DNS record type for a domain' – a clear verb+resource+scope. It distinguishes itself from the sibling tool 'dns_lookup_all' by emphasizing 'specific' record type, making its intent unambiguous.

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

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

The phrase 'specific DNS record type' implies this tool is for individual lookups rather than bulk operations, but alternatives like 'dns_lookup_all' or 'reverse_dns' are not explicitly mentioned. Clear context but no explicit when-not guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the bar for added behavioral disclosure is lower. The description adds useful context about the return format: results are 'grouped by type with TTLs and values,' which goes beyond the annotation safety profile and helps the agent anticipate the response structure.

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

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

The description is two sentences long, front-loads the core action ('Query all major DNS record types'), and contains no fluff. Every word contributes to understanding the tool's purpose and output, making it highly concise and well-structured.

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

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

For a simple one-parameter tool with an output schema and comprehensive annotations, the description is quite complete. It covers what is queried, the return grouping, and the efficiency aspect ('in one call'). A minor gap is that 'major' record types are enumerated but not exhaustive (e.g., no SOA, SRV), which could be slightly ambiguous, but this does not significantly detract from completeness.

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

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

Schema coverage is 100% for the single 'domain' parameter, which already includes a description and example. The tool description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Query') and clearly identifies the resource ('all major DNS record types') and scope ('for a domain in one call'). It distinguishes itself from sibling tools like dns_lookup by emphasizing the comprehensive coverage of multiple record types in a single operation.

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 implies the tool is for comprehensive DNS lookups across multiple record types, grouping results by type. It does not explicitly name alternatives or exclusions (e.g., when to use dns_lookup instead), but the 'all major DNS record types' phrasing provides enough context for an agent to infer appropriate usage.

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

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

Goes far beyond readOnly/openWorld/idempotent annotations by detailing fan-out across sources, the exact result keys, soft-fail behavior for the USPTO API, and the fact that empty sections mean real 'no data' rather than a bug. It also explains name resolution and private-company fallback behavior.

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

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

The description is long but every clause earns its place; it packs trigger examples, source list, return shape, and resolution semantics into one dense paragraph. It is front-loaded with the key instruction ('ALWAYS PREFER... holistic view') before enumerating details.

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 eight data sources, two parameters, and no output schema, the description covers input resolution, return structure, failure semantics, and expected empty results. Nothing an agent needs to decide when to call or how to interpret the result 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?

Though the schema already covers `type` and `value` well, the description adds meaning: `type` values are interchangeable, `value` accepts ticker, zero-padded CIK, or company name, and names resolve via EDGAR's company-name match. This reduces ambiguity an agent would otherwise have.

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 identifies a clear action ('full cross-source profile... in ONE parallel call') and a specific resource (US public company across SEC, patents, contracts, FDA, etc.). Trigger examples such as 'brief me on Tesla' make the intent unmistakable and distinguish it from more focused sibling tools like resolve_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?

Explicitly tells the agent to 'ALWAYS PREFER' this tool over chaining single-pack lookups when the user wants a holistic view, and provides clear trigger phrases. It also states input forms (ticker, CIK, name) and expected behavior for private companies, so an agent knows when the call is still appropriate.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds meaningful context by mentioning 'clear sensitive data' and 'stale context', which explains why deletion is appropriate without contradicting annotations.

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

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

The description is three short sentences, front-loaded with the core action and followed by usage guidance. Each sentence earns its place with no wasted words.

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

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

For a simple one-parameter destructive tool with strong annotations and no output schema, the description is complete. It covers what the tool does, when to use it, and how it relates to sibling tools, leaving no important gaps.

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

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

The schema has 100% coverage for the single 'key' parameter, and the description's 'by key' aligns with it. However, the description provides no additional parameter-specific semantics beyond what the schema already states, so the baseline of 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 uses a specific verb ('Delete') and resource ('previously stored memory by key'), immediately clarifying the tool's action. It also distinguishes itself from sibling tools by pairing with 'remember and recall', making its place in the memory toolset clear.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember and recall', giving clear usage context and implicit guidance on alternatives.

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

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

Annotations already cover read-only, open-world, and idempotent behavior. The description adds valuable context about the internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations and helps set expectations.

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 main purpose, followed by process details and use cases. No fluff or redundancy; every sentence adds 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?

Simple tool with two well-documented parameters and no output schema. The description explains output format ('single text blob ready to drop at site-root/llms.txt') and the exact behavior, making it complete for agent decision-making.

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

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

Schema coverage is 100% with both parameters described in detail. The description adds minimal parameter-specific semantics beyond stating 'any URL' and max_links default/max in the schema. Baseline of 3 applies because schema already carries the semantic load.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL' with a specific verb, resource, and output. It distinguishes from siblings by focusing on the llms.txt format and mentions the target AI crawlers.

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 usage contexts ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), but does not explicitly name alternatives or when not to use it. This is clear context without exclusions, matching a 4.

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

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

With annotations already declaring readOnlyHint=true and idempotentHint=true, the safety profile is covered. The description adds extra behavioral context: return fields, default filtering to active subscriptions, and caller scoping. It omits potential limits/errors, but for a simple list this is sufficient.

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

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

The description is two sentences, front-loaded with purpose, then return fields and usage context. Every sentence adds value with 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?

For a simple list tool with one well-documented parameter, thorough annotations, and a return field list in the description, the description fully compensates for the missing output schema. It covers what, when, and why.

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 include_inactive with its default. The description's mention of 'active subscriptions' aligns with the parameter but doesn't add new syntax or behavior details. 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 states a specific verb 'List' with a clear resource 'the caller's active subscriptions', and distinguishes from siblings like subscribe/unsubscribe by focusing on review. It also enumerates return fields, making the tool's scope explicit.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel', which directly inform when to use this tool relative to subscribe/unsubscribe. This is actionable 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?

Though annotations are all false, the description discloses important behavioral traits: the claim_token return mechanism, rate limiting ('5 per identifier per day'), cost/free status, and the team's daily digest process. It also clarifies that filing without an account returns a claim_token, adding context beyond the annotation set.

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 (9 sentences), but every sentence serves a purpose: purpose, usage, exclusions, formatting guidance, claim_token flow, roadmap impact, rate limit, and cost. It is front-loaded with the core purpose and organized logically. It earns a high score, though it could be tightened without losing essential info.

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

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

For a tool without an output schema, the description compensates by explaining what the tool returns (claim_token on first use, status on later reads), when to use it, what to avoid (paste user prompts, external tools), and behavioral limits (rate limit, free). The description fully covers the tool's scope and usage for an agent.

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

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

Schema coverage is 100%—all four parameters have detailed descriptions, so the baseline is 3. The description adds a usage example for claim_token and clarifies the relationship between filing and later reading, but the schema already explains each parameter's role thoroughly. No significant param semantics are added 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 opens with a clear, specific purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature/data_gap, praise), which distinguishes this tool from siblings like ask_pipeworx or discover_tools. The verb 'Tell' and resource 'Pipeworx team' make the intent 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?

Provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data (bug)...') and explicit exclusions ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). This is a model example of usage direction, including what not to do.

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 readOnly/idempotent annotations, the description adds meaningful behavioral traits: aggregated from CF analytics-engine, no PII, only (pack, tool, count), and cached 5min-1h depending on window. This gives the agent important expectations about data provenance and freshness without contradicting annotations.

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

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

The description is front-loaded with the purpose and output, then uses a terse bulleted 'Useful for' list and a compact provenance/caching note. Every sentence provides distinct value with 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?

Given the simple one-optional-parameter signature, rich annotations, and absence of an output schema, the description covers purpose, output contents, use cases, data provenance, and caching. It is sufficient for an agent to decide when and how to call this tool.

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

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

The single 'window' parameter has complete (100%) schema coverage, including an enum and an explanatory description of how shorter vs longer windows behave. The tool description only mentions the window values without adding new parameter-level meaning, so 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?

Description states a specific verb and resource: 'Returns the top tools, top packs, and total call volume' over a window, clearly distinguishing it as a usage-aggregation tool. It differentiates from siblings like discover_tools by framing it as 'what other AI agents are calling on Pipeworx right now.'

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 cases via a 'Useful for' list with three concrete scenarios, giving clear context for when to invoke. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail beyond that: how partition checks work, placeholder filtering, the fill check against live CLOB depth, and explicit caveats like 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and invocation modes. A few sentences could be trimmed without losing value, but it remains focused and information-dense.

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

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

Despite lacking an output schema, the description fully documents the response shape (opportunities[], partition_check{...}), explains edge cases (thin_legs, skipped_low_similarity, placeholder fractions), and provides actionable trade/no-trade criteria. It also references a sibling tool for follow-up sizing, making it self-sufficient.

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?

While schema coverage is 100%, the description enriches both parameters with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains what each mode does, and clarifies accepted input forms ('Full Polymarket URLs also accepted'). This goes well beyond the schema's one-line 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by explaining its unique detection method and by pointing to polymarket_fill_risk for custom sizing.

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

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

Explicit guidance is provided for each invocation mode: 'Call with NO args for a trending_scan', 'pass event for...', 'pass topic for...'. It also states when one mode is recommended over another ('event (recommended for a specific market)', 'topic (for cross-event scanning)') and names an alternative tool: 'For custom sizing use polymarket_fill_risk.'

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

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

The description goes far beyond annotations, detailing the five model families, response segments, edge calculation (net of slippage, Kelly caps), 1h caching, diagnostics, and the 24h-move warning. No contradiction with readOnly/idempotent annotations.

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

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

The description is long but densely packed with valuable information, using CAPS labels for segments and knobs. It is front-loaded with the core purpose and then systematically covers model families, knobs, and response structure. Every sentence contributes, though it could be better organized into sections.

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?

There is no output schema, but the description meticulously documents the response shape (by_segment, fed_candidates, _diagnostics) and the logic behind each model family, gates, knobs, and caching. This makes the tool's behavior fully comprehensible for an agent.

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

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

Schema description coverage is 100%, so the schema already explains every parameter richly. The description adds some rationale (e.g., why min_partition_leg_kelly exists for partition arbs) but does not significantly enhance parameter 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx disagreement and edge detection.

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

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

It explicitly states the intended use case ('what should I bet on today') and describes the tradeable-edge knobs for filtering. It doesn't name alternative tools, but the context is clear enough for an agent to decide when this tool fits, and it notes limitations (e.g., Fed bets unreliable).

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those: historical depth limited by a 60-day TTL, snapshots only written on cache-miss (so gaps mean no scan), decay computed from daily closes rather than intraday, and detailed response structure. This significantly enhances behavioral understanding 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 well-structured with clear sections (purpose, args, response, limits) and is front-loaded with the core question it answers. Every sentence adds value, but it is somewhat dense and could potentially be tightened. Still, it remains readable and organized.

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 thoroughly explains response structure (tracked[], expired[], snapshot_dates[]) and each field's meaning. It also covers limitations (TTL, cache-miss behavior, close-based decay) and why gaps occur. For a telemetry tool with historical dependencies, this is highly 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% with clear parameter descriptions. The description adds the concept of 'snapshot family' for the window parameter and clarifies defaults, but mostly restates schema information. While it doesn't add many new details, the family terminology gives additional meaning beyond the schema's simple enumeration.

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

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

The description clearly states what the tool does: 'Edge persistence and decay telemetry' built from daily snapshots, answering a specific question about how long an edge has existed. This is a specific verb+resource combination that distinguishes it from sibling tools like polymarket_edges, which likely provides current edge calculations.

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

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

The description provides clear context for when to use this tool: to differentiate between fresh vs. old wide edges and to understand if an edge is shrinking. It doesn't explicitly name alternative tools or provide when-not-to-use guidance, but the intended use case is well implied. The line 'the median lifespan is your competition clock' gives practical context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description doesn't need to repeat that. It adds valuable behavioral context: walks the order book ladder, returns specific metrics, interprets size_usd differently by mode, and warns about partial fills converting an arb into unhedged directional risk. This goes well beyond the structured annotations.

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

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

The description is long but every sentence carries critical information. It is front-loaded with the core purpose, then uses labeled sections (SINGLE-MARKET and BASKET) to organize mode-specific behavior, and ends with usage guidance. No fluff or redundancy; it earns its length.

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

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

For a tool with two modes, four parameters, and no output schema, the description is remarkably complete. It covers all return fields, per-leg details, risk warnings, and even identifies the dominant loss mode in real arb-bot P&L. The threshold guidance and references to siblings provide full context for the agent's decision-making.

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?

Even though schema coverage is 100%, the description adds significant meaning beyond the schema. It explains how size_usd changes interpretation (max spend vs target proceeds vs settlement notional), how side defaults work in basket mode (auto from partition sum), and that market and event are mutually exclusive modes. This deepens the agent's understanding of parameter combinations.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by explaining when it should be used (before polymarket_arbitrage or polymarket_edges trades) and details two distinct modes (single-market and basket), making its purpose unambiguous.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround not capturable on thin books) and differentiates between single-market and basket usage, providing clear context and alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses failure modes, safety fields, compatibility codes, temporal mismatch handling, unclassified legs never being paired, and the gross-vs-net fee caveat. It also clarifies that null temporal_alignment means unknown rather than aligned, which is exactly the kind of nuance an agent 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 long but well-structured with labeled sections and a front-loaded definition. Every major section adds operational detail, though there is some redundancy around temporal_alignment_unknown and the null-value explanation, preventing a perfect structure score.

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

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

With no output schema, the description compensates by detailing the response shape: leg-by-leg prices, matched top_spreads_pp, per-entry flags, skipped cross-type/subtype counters, fees_note, and the temporal_alignment object. It also covers edge cases like unclassified legs and low-confidence pairings, making it sufficiently complete for safe invocation.

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

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

The schema already documents all three parameters with 100% coverage, but the description adds mode semantics: topic auto-fetches matching events on both venues, while explicit ticker/slug override the topic-mapped side, and both modes run the identical matcher. This extra context helps an agent choose meaningful parameter combinations.

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

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

The description states a specific computation: the Kalshi−Polymarket spread for the same resolving question, with concrete output fields like top_spreads_pp. It differentiates the tool from sibling Polymarket tools by emphasizing the cross-venue comparison and both modes of operation.

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 defines two usage modes: topic shortcuts for pre-mapped macro events, and explicit kalshi_event_ticker/polymarket_event_slug for custom pairings. It also gives important cautionary guidance that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not name sibling tools as alternatives, so it stops short of a 5.

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

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

Annotations already declare read-only and idempotent, and the description adds meaningful behavioral context: scoping to the agent's identifier (anonymous IP, BYO key hash, account ID) and the ability to list all keys when the argument is omitted. No contradiction with annotations; only minor details like return behavior are missing.

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 front-loaded action, clear examples, and no filler. Every sentence adds value—action, use case, scoping, and workflow pairing.

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 no output schema, the description covers the core behavior, usage context, and scoping. It lacks explicit return-value details, but they are largely inferable for a retrieval tool, so it is nearly 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% and the schema already explains the optional key and omit-to-list behavior. The description reinforces this with examples but does not add significant new parameter 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?

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also covers the alternative behavior of listing all keys. It explicitly distinguishes from sibling tools by naming remember and forget as the counterparts.

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 concrete when-to-use guidance: 'Use to look up context the agent stored earlier' and gives examples like target ticker and research notes. It also points to alternatives: 'Pair with remember to save, forget to delete,' so the tool's role in the workflow 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 cover the overall safety profile (readOnlyHint, idempotentHint, etc.). The description adds important behavioral context: the feed is persisted, mark_read:true flags returned events so future calls only show newer ones, and each event contains source and citation_uri. This goes beyond the annotations by explaining the side-effect of mark_read.

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

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

The description is a single paragraph of four sentences, front-loaded with the core purpose. It packs in filtering, return details, mark_read behavior, and an HTTP alternative without excessive verbosity. Slightly dense but well-structured.

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

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

With no output schema, the description does a good job of explaining return content: 'each carries source, citation_uri (pipeworx:// when available), and the raw event payload.' It covers filtering, mark_read, and the persisted feed. It doesn't specify the exact array structure, but the 'each' wording implies a list, which is 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 coverage is 100%, so the baseline is 3. The description adds value with a concrete type example ('sec_8k'), clarifies that 'since' is an ISO timestamp, and explains the consequence of mark_read ('so the next call only shows newer ones'). This provides context beyond the raw schema descriptions.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts) and verb ('Pull'), and distinguishes it from siblings like list_subscriptions by emphasizing 'alerts' and 'persisted feed.'

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

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

The description provides clear usage context: it mentions polling, filtering by type and since, and the optional mark_read side-effect. It also offers an alternative access method via HTTP for scripts/dashboards. However, it does not explicitly contrast with sibling tools like subscribe/unsubscribe, so it lacks when-not guidance.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details valuable behavioral traits: fanning out to SEC EDGAR, GDELT→GNews fallback on rate limits or 5xx, USPTO soft-fail due to PatentsView sunset, and the specific `since` format handling. It also discloses return structure. 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 dense but every sentence earns its place: it front-loads the purpose with natural language, explains sources and fallbacks, provides parameter guidance, return shape, and an alternative tool. The structure is logical and efficient, with no filler.

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

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

Despite having no output schema, the description covers return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It handles complexity (multiple sources, fallback, parameter variants) and provides enough context for an agent to invoke it correctly and interpret results. It is 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, but the description goes well beyond. It gives concrete examples for `since` ('2026-04-01', '7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It clarifies `value` can be a ticker or CIK. This adds meaningful semantics not present in 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 opens with natural-language queries ('What's new with X') and then explicitly states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the resource (company change feed) and the action (retrieving recent changes), and distinguishes itself from the sibling tool entity_profile at the end.

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

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

The description gives clear usage context: for time-boxed change feeds, with explicit fallback logic and source behavior. It also states when NOT to use it: 'Use entity_profile instead when you want the static profile... regardless of window.' This is an explicit alternative and exclusion.

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 context beyond annotations: persistence differences (authenticated vs. anonymous), scoping by identifier, and complementary tools. It doesn't contradict annotations but could mention overwrite behavior; idempotentHint already covers that.

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?

Each sentence adds value: purpose, usage, storage mechanics, retention, and pairing. It is efficiently front-loaded with the core action and not verbose.

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

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

For a simple two-parameter tool with no output schema, the description covers everything needed: what it does, when to use it, how storage works, persistence, and related tools. 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 description coverage is 100% for both parameters, and the description's examples ('resolved ticker', 'target address') reinforce the schema's examples without adding new syntactic detail. The schema already carries the weight.

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

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

The description clearly states a specific verb ('Save') and resource ('data the agent will need to reuse later'), and explicitly distinguishes itself from siblings like recall and forget by mentioning pairing. This makes the tool's 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?

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'), and names alternatives ('Pair with recall to retrieve later, forget to delete'). This fully covers usage boundaries.

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 signal read-only/idempotent safety, but the description goes well beyond that: identifiers are labeled by source, unresolved identifiers are returned under `unresolved`, ambiguous FIGI matches return candidates instead of asserting, LEI/FIGI enrichment degrades gracefully, and ISINs resolve to the issuing legal entity via GLEIF. No contradiction with annotations.

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

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

The description is long, but every section earns its place: purpose, supported types, edge cases, degradation behavior, and practical value. It is structured rather than rambling, though it could be marginally tighter and more paragraph-separated given its density.

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?

There is no output schema, so the description carries the full burden of explaining return behavior. It explicitly covers what is returned for company and drug types, how unresolved identifiers are handled, what happens with ambiguous names, and the graceful degradation path. An agent has enough to call and interpret the result 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%, so the baseline is 3. The description adds substantial meaning beyond the schema by detailing the company identity spine (CIK/ticker/company_name/LEI/FIGI), source attribution, ISIN-to-LEI behavior, ambiguity handling, and the drug return fields (RxCUI, ingredient, brand, citation). This materially helps an agent pass the right 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 states a specific verb and resource: it resolves user-spoken names to canonical/official identifiers that other tools require. The example queries ('ticker for', 'CIK', 'LEI', 'RxCUI') make its scope unmistakable, and the explicit 'Use FIRST whenever you have a name but need an ID' distinguishes it from siblings like entity_profile or compare_entities.

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

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

It gives a very clear trigger: 'Use FIRST whenever you have a name but need an ID', plus enumerated supported types and query patterns. It even explains what to do on ambiguous matches. However, it does not explicitly name alternatives or give when-not-to-use conditions, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral detail that a PTR record may not exist ('if available'), implying a possible empty or null result. This adds value beyond the annotations, though it does not explain other edge cases (e.g., invalid IP formats).

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 concise sentences that front-load the primary purpose and then mention the return value. Every word is informative, with no redundancy or 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 the tool's simplicity (one parameter, comprehensive annotations, and an output schema), the description is complete. It explains the core behavior (reverse DNS lookup) and the expected outcome (PTR record if available), which is sufficient for an agent to invoke it correctly.

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

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

The schema fully documents the single 'ip' parameter with type 'string' and an example. The description does not add meaning beyond what the schema already provides; it simply refers to 'an IP address'. With 100% schema coverage, a 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 function: 'Find the hostname for an IP address via reverse DNS lookup.' This specifies the exact verb ('find') and resource ('hostname for an IP address'), distinguishing it from sibling DNS tools like dns_lookup and dns_lookup_all.

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

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

The description provides clear context for when to use the tool: when you need the hostname for an IP address using reverse DNS. It does not explicitly mention alternatives or exclusions, but the intended use case is apparent from the phrasing.

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

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

Annotations already declare readOnly/idempotent, so the description adds value by disclosing that it internally calls ai_visibility_check, ranks entities, and returns fields like score, confidence, and signal density. This is beyond annotations without contradiction.

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

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

Three tight sentences with every sentence contributing: what it does, how it works, and a use-case example. No fluff, front-loaded with the core action.

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 explains the return type (ranked list with score, confidence, signal density) and the operational flow. Combined with annotations and schema, it provides a complete understanding for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'entities' parameter by noting the first entry is treated as the subject for narrative, adding semantic meaning beyond 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 the tool's function: 'Compare AI visibility across multiple entities side-by-side' with specific actions (probes with ai_visibility_check, ranks by score, surfaces most/least recognized). It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query, implying comparison across competitors. It doesn't explicitly exclude alternatives like ai_visibility_check for single-entity checks, but the context is sufficient.

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

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

The description goes well beyond the annotations by disclosing partial failure behavior, the 5-30s first measurement delay, and the sources_failed field. It also confirms the read-only nature by describing it as a 'check' that 'degrades gracefully' without side effects. 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 front-loaded with purpose, then usage, then output details, then limitations. Every sentence conveys essential information; despite being somewhat long, it is dense and well-structured with no filler.

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

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

For a composite tool with no output schema, the description lists all returned fields, covers ecosystem scope, latency expectations, and failure handling. It is fully self-contained and gives the agent all necessary context to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level detail beyond the schema; it implies the 'version' parameter via 'recent alternative versions' but does not explain parameter semantics beyond what the schema already states.

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

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

The description clearly states it is a composite check for npm packages, listing specific data sources (deps.dev, bundlephobia) and the exact types of information returned (license, advisories, bundle size, etc.). This is far more specific than the title and distinguishes it from any sibling 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 states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear direction to an alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description goes beyond annotations by revealing the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, the 200K char cap with truncation flag, and that outputs include offsets for verbatim verification. 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?

Four sentences, each purposeful: first states the core function, second explains when to use it and the benefit, third notes the integration with a sibling tool, and fourth gives technical details. No repetition or filler; information is front-loaded and tightly packed.

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?

Though there is no output schema, the description fully explains the return format (passages with character offsets and similarity scores), truncation behavior, and the 200K char limit. It also describes the end-to-end workflow with ask_pipeworx_grounded, making the tool self-sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual examples for text ('SEC 10-K body, an article, a long tool result') and clarifies the query type, plus the character cap, which enriches parameter meaning beyond the schema's bare descriptions. However, it doesn't add distinct semantics for the limit parameter since the schema already covers its bounds and default.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies the exact operation: pass text and a natural-language query, receive top-N passages with character offsets and similarity scores. It distinguishes itself from siblings by emphasizing it works on already-fetched text rather than querying a knowledge base, and explicitly pairs with ask_pipeworx_grounded.

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

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

Provides explicit usage context: 'Use when the record is too big to cram into the prompt' and recommends a complementary workflow with ask_pipeworx_grounded. This tells the agent when to choose this tool and how to combine it with a sibling, which is excellent 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?

Adds rich behavioral context beyond annotations: always-on feed, optional email/SMS/webhook with specific constraints (SMS 10/day cap, phone verification), webhook HMAC signing secret returned only once, and auto-disable after 10 consecutive failures. No contradiction with annotations.

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

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

The description is long but dense, with every sentence containing operational detail. It is front-loaded with purpose and prerequisites, then types, then delivery. While longer than typical, it earns its length for a complex tool.

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

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

Covers purpose, return value, prerequisites, type examples, delivery channels, limits, and webhook security. However, it omits patent_grant and clinical_trial from the description text, though the schema covers them. Overall complete for a tool of this complexity.

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

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

Schema already has 100% description coverage for all parameters. The description adds semantic interpretation (e.g., items:['5.02'] = officer change) and explains delivery channel behaviors, supplementing the schema with real-world meaning.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and clearly notes it returns the new subscription id. This distinguishes subscribe from sibling tools like list_subscriptions and unsubscribe by the action of creating.

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 and prerequisites (requires Pipeworx OAuth account; anonymous + BYO cannot persist) and details supported subscription types. It does not explicitly name alternative tools, but the usage context is well-defined enough for an agent to choose this over read-only alert tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds contextual transparency by stating the output is drawn from 'the live catalog of thousands of tools' and that results include 'the exact tool + argument shape' for each example. This goes beyond the annotations 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 longer than average but front-loaded with examples of user queries and a clear summary of purpose. Every sentence contributes value, including the category list and the explicit call pattern. It is slightly dense but appropriate for an onboarding tool.

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

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

Given the simple schema (one optional parameter) and the rich annotations, the description fully covers purpose, input semantics, output shape, and when to use it. It even references related meta-tools, making it self-sufficient despite the lack of an output schema.

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

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

Schema coverage is 100% and already lists the acceptable topics, so the baseline is 3. The description enhances this by explaining that passing `topic` focuses the results and that omitting it returns a 'cross-category spread', adding meaningful usage semantics beyond the raw enum values.

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

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

The description clearly identifies the tool as the onboarding entry point for Pipeworx, with specific verbs like 'returns category-bucketed example questions' and 'call with no arguments for the full spread'. It distinguishes itself from siblings by positioning it as the 'FIRST' tool to use when you don't know what Pipeworx can do, explicitly referencing meta-tools.

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

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

Provides explicit guidance on when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional `topic` parameter and the no-argument default. However, it does not explicitly mention when not to use it or contrast it with the sibling `discover_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 indicate this is a mutation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds valuable context: ownership enforcement and the fact that the row is deactivated, not deleted, which explains why it is not destructive. It also clarifies that historical events remain available, going beyond the annotations 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 two sentences long, front-loaded with the core action, and contains no filler. Every sentence adds value: the first states the action, the second explains constraints and consequences. This is a model of 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?

For a simple tool with one parameter and no output schema, the description covers all essential aspects: what it does, who can use it, and what the outcome is. It even mentions related tool 'recent_alerts' for context about historical events. The description is fully sufficient for an agent 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?

The input schema fully documents the only parameter 'id' with a clear description, including that it is returned by subscribe. The description's reference to 'by id' adds little beyond the schema, so with 100% schema coverage, 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 action ('Cancel a subscription') and the method ('by id'), and distinguishes the tool from siblings by explaining that it deactivates rather than deletes, which is a different effect from what similar tools might do. The verb 'Cancel' is specific and the resource is unambiguous.

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

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

The description provides clear context for when to use the tool, including ownership restrictions ('you can only cancel your own subscriptions') and the behavioral outcome (deactivation with historical events preserved). However, it does not explicitly mention alternatives or state when not to use it, so it falls slightly short of a fully explicit usage guideline.

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 signal read-only, idempotent, and non-destructive behavior; the description adds critical semantics: the two processing paths, the verdict enum, and the key caveat that could_not_verify means the check did not happen and must not be treated as evidence. It also clarifies unsupported vs could_not_verify.

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 it is front-loaded with purpose and examples, and every sentence carries functional value. The initial list of natural-language phrasings is slightly redundant yet aids NLU triggering.

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 there is no output schema, the description thoroughly covers return values (verdicts, evidence with citation, reasoning), the two execution paths, and the crucial distinction between could_not_verify and unsupported. It also frames the tool as a one-call replacement for multi-step processes, providing complete operational context.

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

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

Schema description coverage is 100%, so both the claim and tolerance_pct parameters are already fully documented in the input schema. The description adds no additional parameter-level detail beyond what the schema provides, hence 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?

Clearly identifies the tool as natural-language claim verification against authoritative sources, with specific examples of claim phrasing. Distinguishes between the SEC EDGAR/XBRL fast path for financial claims and the grounded pipeline for all other claims, and notes it replaces 4–6 sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides guidance on when to expect the structured vs grounded path. It does not name alternative sibling tools or provide when-not-to-use conditions, but the context is clear and useful.

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