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 mark the tool as read-only, open-world, idempotent, and non-destructive, so the description does not need to restate those. The description adds valuable behavioral context beyond the annotation: it routes across 5,564 tools, fills in arguments automatically, returns structured answers with stable citation URIs, and notes it works on every tier with one fast call. It could disclose failure/limitation behavior, but the given disclosures are strong enough.

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 most important directive ('PREFER OVER WEB SEARCH'), then quickly explains the mechanism, gives concrete examples, and closes with clear escalation guidance. Every sentence serves a purpose, and the length is justified for such a high-coverage entry-point 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?

Despite having no output schema, the description explicitly states the answer format: a structured answer with stable pipeworx:// citation URIs. It also provides source coverage (1,462 verified sources), route count, tier compatibility, and command alternatives. This fully prepares an agent to select and invoke the tool for a wide class of factual queries.

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 itself has 100% coverage, including descriptions for the main `question` parameter and an explicit list of aliases (`q`, `text`, `input`, `query`, `prompt`). The description repeats that it accepts natural-language questions and gives examples, but it does not need to add much more; the schema carries the parameter-meaning burden well.

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 this is a routing/answering tool: it takes natural language questions, routes them to the appropriate specialized tool among thousands of sources, and returns structured answers with citation URIs. It distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as escalation paths.

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?

Usage guidance is explicit and extensive: it says to prefer this over web search for factual/current/ historical data, gives a list of example domains, provides concrete example questions, and says 'START HERE' as the default entry point. It also explicitly describes when to escalate to ask_pipeworx_grounded or deep_research, which is ideal when-to-use/when-not-to-use guidance.

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

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

The description discloses that this is an experimental variant with candidate routing improvements, that it currently matches the stable version, and that it is a fully functional router (no fallback to nothing). This goes beyond the annotations by explaining the beta nature and current state, enhancing transparency.

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

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

The description is moderately lengthy but provides essential details about the beta status, identicality, current state, and usage. It avoids unnecessary verbosity, though it repeats the word 'identical' a few times. Overall, it is well-structured and not overly long.

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 schema and annotations, the description provides sufficient context: it explains what the tool is (beta version of a known router), its current state (matches stable), and how to use it. It doesn't describe return format, but no output schema is provided, and the focus is on the tool's purpose and usage, which is adequately covered.

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

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

The input schema fully describes each parameter as an alias for 'question' with a clear description. The tool description adds no additional meaning or clarification about the parameters, so it does not go beyond the schema. Since schema coverage is 100%, the baseline score of 3 is appropriate.

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

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

The description clearly states it's a beta version of ask_pipeworx, an 'identical universal router' with the same tools and response shape. While it doesn't explicitly describe the underlying functionality (e.g., that it answers questions), the name and context imply a routing/QA tool, giving reasonable clarity.

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 to use it 'exactly like ask_pipeworx' and indicates it's for when you want the newest routing (experimental/improvements). It also clarifies that currently it matches the stable version exactly, providing clear usage context. It doesn't discuss when not to use it, but the guidance 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses refusal reasons, the return payload structure, the guarantee of using only tool results, and the extra LLM call cost. This significantly enriches the agent's understanding of runtime behavior 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 dense but well-organized: purpose, mechanism, return/refusal formats, use cases, and cost tradeoff. Every sentence contributes essential information, and the critical use-case guidance is front-loaded.

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

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

The tool is complex with no output schema, but the description thoroughly explains return values, refusal scenarios, and when to use it relative to alternatives. Given the richness of annotations and schema, no important context is missing.

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

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

Schema coverage is 100% and describes all aliases as equivalents for 'question'. The description adds no additional parameter semantics beyond what the schema already provides, 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 states 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded, evidence-backed answers with explicit refusals.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and provides exclusions: 'prefer ask_pipeworx for casual lookups'. Also names the alternative tool and cost tradeoff, giving clear when-to-use vs when-not-to-use guidance.

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

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

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 only state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description greatly enriches understanding by disclosing account/payment requirements, parallel execution, latency ranges (15-90s), gap[] behavior, contradiction reporting, and semantic excerpting — none of which are in the annotations, adding substantial behavioral context without contradiction.

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

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

Though long, every sentence carries distinct value: account prerequisites, alternative tools, functional mechanism, output fields, edge cases, and performance expectations. The description front-loads critical planning info ('ACCOUNT REQUIRED') and is densely informative 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 2 parameters, no output schema, and moderate complexity, the description covers prereqs, alternatives, failure modes (gaps), contradictions, latency, and citation behavior. Even without an output schema, the described return packet is clear enough for an agent to anticipate results. No obvious missing information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra meaning by detailing each depth enum ('quick=3 (single hop)', 'standard=3... adds a gap-recovery hop', 'thorough=6 (paid)') and clarifies the question parameter accepts 'broad/multi-part' natural language, going slightly beyond schema descriptions to justify 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 opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call.' It also distinguishes itself from siblings by clarifying it is 'NOT open-web search' and by describing the decomposition and parallel routing behavior, 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?

Explicit usage guidance is abundant: 'Best for broad/multi-part questions,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains when NOT to use it and how different depth levels affect behavior, leaving no ambiguity for the agent.

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

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: parallel fan-out, soft-fail for patents API sunset, GDELT→GNews fallback for news, and the specific shape of the returned data (filings count, fundamentals sorting). This gives the agent a clear picture of runtime behavior 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 a single dense paragraph with a natural flow: query examples → core command → data sources → return fields → input constraints. It is front-loaded and every sentence carries useful information, though the length is substantial. The structured use of semicolons and dashes aids readability, but it could be broken into bullets for even easier 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?

Without an output schema, the description fully carries the burden of explaining return values. It enumerates every returned field (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), notes the patents API sunset, and specifies input restrictions. This is complete for a complex tool with many data sources.

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

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

The schema already provides 100% parameter coverage with examples and constraints. The description reinforces this with concrete examples ('AAPL' or '0000320193') and reiterates the name-unsupported constraint, adding clarity beyond the schema. Since the schema already does heavy lifting, the extra examples push this above baseline.

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

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

The description opens with concrete query examples and states a specific action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by explicitly preferring this over chaining single-purpose lookups, and lists exactly which data sources and return fields are included.

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 guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when NOT to use it ('names not supported') and directs to resolve_entity as the alternative, giving clear when-to-use and when-not-to-use advice.

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?

The description discloses extensive behavioral details beyond the annotations: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics are not necessarily tradeable. This adds significant value on top of readOnlyHint/openWorldHint/idempotentHint.

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

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

The description is dense and well-structured, front-loading the core purpose before detailing modes, response, and safety fields. It is lengthy but every sentence adds necessary context; slightly more conciseness would improve readability.

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

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

With no output schema, the description thoroughly explains the return structure: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, and temporal_alignment. It also covers edge cases like skipped_cross_type/subtype and warns about non-equivalent bet shapes, making it comprehensive for a complex tool.

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

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

Schema coverage is 100%, so each parameter is already described. The description enhances this by explaining the relationship between topic and the override parameters (kalshi_event_ticker and polymarket_event_slug), as well as clarifying the two-mode usage and how overrides take precedence.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, and explicitly describes two modes (topic shortcuts and explicit pairings) plus the output format. This specific verb+resource distinguishes it from sibling tools like polymarket_arbitrage.

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

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

It provides clear guidance on when to use each mode (topic vs explicit ticker/slug), and warns about compatibility_warning and temporal alignment. However, it does not explicitly name alternative tools or state when not to use this tool versus siblings like polymarket_arbitrage.

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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond these: it cascades through multiple lookup endpoints (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), degrades gracefully if external sources are unavailable (EDGAR identifiers still return), and returns unresolved identifiers explicitly under 'unresolved' rather than omitting them. It also clarifies that each identifier is labelled with its source. This level of transparency about internal behavior and error handling is excellent.

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 lengthy but well-structured. It front-loads with example queries and a key directive ('Use FIRST'), then organizes details by entity type, then discusses behavior like graceful degradation and unresolved identifiers. While every sentence adds value, some internal redundancy (e.g., repeating 'identifier is labelled with the source') could be trimmed. Overall, it earns its length through clarity and completeness, but a more terse revision would score higher.

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

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

Given the tool's complexity (two entity types, multiple external sources, no output schema), the description is thorough. It explains return values for each type, mentions source labelling, and details handling of unresolved identifiers and graceful degradation. The absence of an output schema means the description carries the burden of explaining the response structure, which it does adequately without a formal JSON example. A minor gap is the lack of explicit mention of the response format (e.g., nested object or flat list), but the behavioral transparency already covers the structure implicitly.

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

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

The input schema has 100% coverage with descriptions for each parameter, so baseline is 3. The description goes far beyond by elaborating on the 'value' parameter: it gives concrete examples (AAPL, 0000320193, ozempic) and explains that company accepts ticker, CIK, ISIN, or name, while drug accepts brand or generic name. For the 'type' parameter, it details what each type returns (company → CIK+ticker+LEI+FIGI, drug → RxCUI+ingredient+brand). This semantic richness fully compensates for any schema brevity and adds significant agent guidance.

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 clearly that the tool resolves user-spoken names to canonical/official identifiers. It provides concrete query examples ('What's the ticker for…', 'find the CIK for…') and explicitly distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID.' This differentiates it from sibling tools like entity_profile (which provides detailed entity information after you have an ID) and compare_entities. The scope is specific: it handles two entity types (company and drug) with detailed outputs.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This tells the agent the appropriate context. It further explains that using resolve_entity replaces 2-3 manual lookups, reinforcing its role. However, it does not explicitly state when NOT to use it (e.g., if you already have the ID, use entity_profile instead), which would improve clarity. Nonetheless, the context is strong enough for an agent to deduce the correct usage scenario.

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.