Bts

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it returns per-model score/confidence/signals/raw_response plus combined view, and clarifies that Anthropic probing requires a BYO key with direct billing by Anthropic. 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 a single dense paragraph but efficiently conveys purpose, default behavior, optional extension, return structure, and use cases. Every sentence adds value, 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?

The description adequately covers purpose, parameters, return format, and usage context. Since there is no output schema, it compensates by describing the return structure. Minor gap: how the visibility score (0-100) is computed is not explained, but it's sufficient for 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 description coverage is 100%, and the description adds meaning beyond schema: it states the default model (Llama-3.3-70b free), the cost implication of _apiKey, and the disambiguation role of 'context'. This enriches the parameter understanding.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the tool's resource: LLM visibility of a business/brand/product/topic. It distinguishes from siblings like ask_pipeworx and deep_research by focusing on visibility scoring, not general Q&A or research.

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

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

The description explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use. It doesn't explicitly state when not to use or list alternatives, but the purpose is specific enough to differentiate.

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 safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: routing across thousands of tools, argument filling, structured output with pipeworx:// citation URIs, and performance characteristics ('one fast call'). No contradiction with annotations; some extra details like error handling are absent but not critical.

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 ideal but well-structured: it opens with a strong directive, then explains the mechanism, provides examples, and closes with alternatives. Each section earns its place, but the length is slightly above what a concise description would use.

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

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

For a complex routing tool with no output schema, the description is remarkably complete. It covers scope, use cases, examples, behavioral mechanism, citations, and alternatives. It gives the agent enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100% with a well-described 'question' parameter and aliases. The description adds usage examples and trigger phrases, but the schema already communicates the natural-language requirement. It doesn't introduce new parameter syntax or formats beyond what the schema provides, so 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: routing factual questions to one of 5,529 tools and returning structured answers with citations. It uses specific verbs like 'Routes' and 'returns', and explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('use ask_pipeworx_grounded...', 'use deep_research...'). It also gives concrete trigger phrases and examples, making the usage conditions extremely clear.

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

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

The description goes beyond the annotations by disclosing that it is a beta with live candidate routing improvements that can change behavior, and that currently no candidate is active so it exactly matches ask_pipeworx. This is valuable context for the agent regarding potential variability. It is consistent with the readOnlyHint, idempotentHint, and destructiveHint annotations, which it does not contradict.

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

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

The description is concise but informative, about three sentences, with the most important information ('Beta version of ask_pipeworx') front-loaded. Each sentence adds essential detail: what it is, current state, usage guidance, and reassurance that it is a full router. No wasted words.

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

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

Given the tool's complexity (universal router with thousands of tools and no output schema), the description is thorough. It explains the experimental nature, the current fallback to stable behavior, how to use it, and that the response shape matches ask_pipeworx. It gives enough context for an agent to confidently invoke the tool and interpret results.

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

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

The input schema already documents all six parameters with 100% coverage, all as aliases for 'question'. The description adds that the tool has 'same arguments' as ask_pipeworx, which confirms the schema but does not provide additional semantic depth. Since schema coverage is complete, 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 this is a beta version of ask_pipeworx, a universal router that handles 5,529 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. The verb 'ask' and resource 'Pipeworx beta' are specific and meaningful.

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 it exactly like ask_pipeworx when you want the newest routing', providing direct guidance on when to use this tool. It also notes that results are compared against the stable router, implying the stable version is the alternative for production use. The statement 'Falls back to nothing — this IS a full working router' clarifies it is a complete tool, not a stub.

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 are readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral context beyond annotations: refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), evidence verbatim quote, and the extra LLM call cost. No contradiction.

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

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

Though longer than a simple one-liner, every sentence adds value: purpose, routing mechanism, output/refusal format, usage guidance, and cost tradeoff. The structure is well-organized and front-loaded with the primary purpose.

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

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

No output schema is provided, but the description fully documents the return value shape and all refusal reasons. It also clarifies behavior when data doesn't directly answer, which is critical for high-stakes use cases. Complete for the tool's complexity.

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

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

Schema coverage is 100%, with description of question and aliases already present in the input schema. The description adds process context (routing, fetching) but no extra parameter-level semantics, so 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and details its behavior: extracting answers only from tool results, returning evidence/refusal, and routing like ask_pipeworx. This distinguishes it from sibling tools by highlighting its grounded, refusal-capable nature.

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 'prefer ask_pipeworx for casual lookups.' Also mentions the cost tradeoff (one extra LLM call), providing clear when-to-use and 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?

Extensive behavioral details beyond annotations: resolution process, fan-out examples, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, wide-spread handling, cancellation rules. Annotations already indicate safety (readOnly, openWorld, idempotent, non-destructive), but description adds rich context.

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 verbose but well-structured with a clear flow: purpose, usage, examples, response shapes, safety. Every sentence adds value, though it could be more concise. Front-loaded with core purpose.

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

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

Covers all relevant aspects: input formats, output structure (without output schema), error cases (low confidence, closed markets), edge cases (wide spread, cancellation rules). No gaps given the tool's complexity.

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

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

All 3 parameters are described in the schema (100% coverage). Description adds examples for 'market', explains 'depth' enum behavior, and details 'include_raw' effects, providing meaning beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies verb ('Research'), resource ('Polymarket bet'), and distinguishes from sibling tools like ask_pipeworx or polymarket_edges by focusing on a single bet.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Does not explicitly mention when not to use or alternatives, but the context is clear enough.

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, and idempotent. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph but front-loaded with example queries for immediate recognizability. Every sentence adds value without redundancy, efficiently packing purpose, guidelines, and behavioral details.

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

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

Despite no output schema, the description adequately covers return format (paired data, citation URIs) and handles the tool's complexity (two entity types with distinct data sources). It provides sufficient context for correct use without omissions.

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 documented. The description goes beyond by clarifying real-world usage: tickers/CIKs for companies, drug names for drugs, and the 2-5 item constraint. It also explains how the 'type' parameter determines data source, adding semantic richness.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one parallel call, distinguishing it from sequential single-pack lookups. It specifies the data pulled for each type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs) and that results are sorted by primary metric, leaving no ambiguity about the tool's purpose.

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

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

Explicit guidance is provided on when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It includes natural language examples and details on entity types and data sources, effectively guiding selection over alternatives.

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

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

Annotations already declare safe read-only behavior. Description adds context about output content (field name, label, type) and intended sequence, enriching 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?

Two efficient sentences: first states purpose and output, second gives usage context. No redundant words, 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?

With no output schema, description adequately explains output fields and purpose. Could mention potential limits but acceptable for a simple listing 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 already describes datasetId, but description adds value by specifying it's the Socrata 4x4 code from search_datasets, aiding correct parameter retrieval.

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 lists columns of a dataset, specifying returned information (field name, human label, data type). It also distinguishes itself from siblings by advising to call this before query_dataset.

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

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

Explicitly advises to call this tool before query_dataset to know available fields, providing clear usage context. Does not mention exclusions but gives concrete 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 cover readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds substantial context beyond that: account requirements and paid tier, expected latency (15-60s, thorough up to 90s), the gaps[] array and promise to never invent answers, contradictions[] for standard/thorough, hop fields, fetchable citation_uri only when resolvable, and semantic excerpting of large records. This far exceeds the annotation baseline.

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

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

The description is long but every sentence earns its place. It is front-loaded with the critical account requirement and alternatives, then moves through mechanism, depth semantics, output shape, citation guarantees, and timing. There is no fluff or repetition; structure is logical and decision-relevant.

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

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

Despite no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop field, and citation_uri behavior. It also covers exclusions for current-news, timing expectations, depth differences, and account prerequisites. This is 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?

Although schema coverage is 100%, the description enriches the depth parameter beyond the enum labels: 'quick=3 (single hop), standard=5 (default; adds a gap-recovery hop...), thorough=8 (paid; adds a full iterative hop...).' It also explains that thorough requires a paid plan, which is not in the schema. This goes well beyond what the input schema provides.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL.' It clearly distinguishes itself from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx.

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 usage rules and alternatives: 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' and 'If you are not signed in, use ask_pipeworx instead.' It also says 'Best for broad/multi-part questions over structured data,' providing a clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context about what is returned (top-N tools with full schemas and examples, ready to call). 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 the purpose and includes useful detail (domain list, return value) without excessive fluff. Every sentence adds value, though it could be slightly more concise.

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

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

Given there is no output schema, the description adequately explains what is returned (tool names, descriptions, schemas with examples). It covers the main use case and the parameter aliases, making it complete enough 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%, with all parameters having descriptions including aliases for 'query'. The description does not add significant parameter meaning beyond what the schema already provides, so 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 'Find tools by describing the data or task' which is a specific verb+resource. It lists many domains (SEC filings, financials, etc.) and distinguishes from sibling tools by positioning itself as a discovery mechanism to find other tools.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it, though it does not explicitly mention when not to use it or name specific 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 idempotency and read-only nature. The description adds context: parallel fan-out across sources, specific return fields, fallback behavior (GDELT→GNews), and soft-fail for patents. Could be more detailed on rate limits or paging.

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

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

The description is a single paragraph but contains all essential info. It is front-loaded with examples and clear purpose. Slightly verbose in listing return fields but justified by 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 covers all return elements (cik, filings, fundamentals, patents, news, LEI) and limitations. Sufficient for an agent to understand inputs, outputs, and edge cases.

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 helpful nuance: zero-padded CIK format and guidance to use resolve_entity for names, which goes beyond basic parameter documentation.

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

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

The description uses specific verbs like 'profile' and 'research' with a clear resource ('US public company'). It distinguishes from sibling tools by advising preference over chaining single-pack lookups and directing names to resolve_entity.

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

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

Explicitly states when to use ('ALWAYS PREFER'), when not to use ('names not supported'), and provides alternatives (resolve_entity). Also notes caveats like patent API sunset.

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

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

Annotations already provide destructiveHint and idempotentHint. Description adds context about clearing sensitive data, but does not detail behavior beyond what annotations convey.

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 concise sentences with purpose, usage guidance, and pairing. No redundant 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?

For a simple tool with one parameter, the description covers purpose, usage, and relationship to siblings. Slight gap on behavior for nonexistent keys, but idempotentHint addresses this.

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 description on key parameter. Description does not add additional parameter semantics beyond what schema provides.

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

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

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

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

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

Explicitly states when to use: context stale, task done, clear sensitive data. This provides clear guidance for choosing this tool over alternatives like remember or recall.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool fetches the page and extracts content, which clarifies the read-only nature and the output format. It does not contradict 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 two sentences plus a bullet list of use cases. It is front-loaded with the core purpose. Every sentence adds value, though the bullet list could be integrated into a single paragraph without loss.

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 well-described parameters and no output schema, the description explains input, process, output format, and use cases. It is fully sufficient for an AI agent to understand when and how to invoke the 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% with both parameters described. The description echoes the schema for url and max_links but adds context about the extraction process. It does not provide new semantic meaning beyond the schema.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with specific steps (fetches, extracts title/description/links, emits markdown). It distinguishes the tool from siblings like scan_competitor_ai_presence by focusing on generation rather than auditing.

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

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

The description lists concrete use cases (client's site indexing, own project drafting, competitor auditing) but does not explicitly exclude alternatives or state when not to use it. The context is clear but lacks direct differentiation from related 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, idempotent, non-destructive. The description adds value by listing return fields and noting the include_inactive parameter, which provides additional behavioral context beyond annotations.

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

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

Two concise sentences that front-load purpose and return fields, then provide usage guidance. No filler; every sentence adds value.

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

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

For a simple list tool with full schema coverage and good annotations, the description fully covers purpose, return fields, usage context, and parameter. No output schema is needed as return fields are described.

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

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

Schema coverage is 100% with a clear description for the only parameter. The tool description does not add extra meaning beyond the schema, so 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 'List the caller's active subscriptions' specifying the verb (List), resource (subscriptions), and scope (caller's active). It also enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises to use the tool 'before adding more or to find an id to cancel', providing context for appropriate usage. While it doesn't name alternatives, the siblings include subscribe and unsubscribe, making usage guidance 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 are all false and offer no safety hints, so the description carries the burden. It discloses key behaviors: anonymous filing returns a claim_token, rate limit of 5/day, free usage, and that the team reads digests daily. It doesn't explicitly state that a persistent feedback record is created, but the token mechanism implies it, so there's no contradiction.

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

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

The description is longer than average but every sentence earns its place: purpose, use cases, exclusions, claim_token mechanics, rate limit, and cost. It is front-loaded with the core action. While comprehensive, it could be tightened modestly without losing substance.

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

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

Given there is no output schema and only four parameters (one enum, one nested object), the description covers all essential behavior: how to file, how to follow up, scope restrictions, rate limits, and cost. It explains the return behavior (claim_token and later status changes) and differentiates from siblings, making the tool self-contained.

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 parameter descriptions are already detailed, so the baseline is 3. The description adds meaningful context: claim_token usage as a standalone follow-up, message content guidance (be specific, don't paste user prompt), and type classification examples. This lifts it slightly above baseline.

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

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

The description clearly states the verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It provides concrete examples (bug, feature/data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on feedback about Pipeworx tools.

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

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

The description explicitly details when to use the tool (wrong/stale data, missing tool, praise) and when not to (tools from other MCP servers). It also explains the claim_token follow-up workflow, giving clear context for calling with just the token to retrieve status.

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

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

Annotations already indicate safe read-only behavior. Description adds context: data source (CF analytics-engine), no PII, caching times (5min-1h), and self-aggregating nature. No contradiction.

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

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

Front-loaded with main purpose, uses bullet points for use cases. Slightly verbose but efficient overall.

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

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

For a simple tool with one optional param and no output schema, description is complete: explains return values, use cases, caching, data source. No gaps.

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

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

Schema covers parameter fully with enum and description. Description adds interpretation: shorter windows for hot now, longer for steady-state, enhancing understanding beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on trending/calling activity.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, checking alignment) and window selection guidance. Lacks explicit when-not-to-use, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant context: it explains the partition filter (drops placeholder slugs), the fill check (theoretical vs. realizable edge), and conditions for not trading (realizable_edge_pp ≤ 0). This goes well beyond annotation data, fully disclosing behavioral traits and limitations.

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

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

The description is well-structured: it starts with the core action, then details each mode, followed by technical constraints (semantic anchor, partition filter, fill check). Every sentence provides essential information—no redundancy. Despite length, it is front-loaded and efficient, earning its length given 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?

Without an output schema, the description fully explains the response structure (opportunities[] with fields, partition_check fields, fill_check details). It covers all parameters, modes, and edge cases (e.g., skipped_low_similarity, placeholders_filtered). The description leaves no significant gaps, ensuring an agent understands inputs, outputs, and logic completely.

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?

Both parameters (event and topic) have schema descriptions, and the description enriches them with examples, expected slugs, and behavioral implications. It explains that event mode walks child markets and performs date-axis/threshold-axis ordering and partition check, while topic mode searches across events. This adds substantial meaning beyond the schema, making the parameters' effects clear.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its unique algorithmic approach and multiple modes (trending scan, event, topic). The verb-resource combination is specific and unambiguous.

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

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

The description provides explicit guidance on when to use each mode: call with no args for trending scan, pass event for specific market partition check, or topic for cross-event scanning. It explains trade-offs (e.g., cross-event catches patterns single-event misses) and includes a fill check to avoid non-tradeable signals. It also references polymarket_fill_risk for custom sizing, offering clear when-to and when-not-to use.

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 provides extensive behavioral details beyond annotations, including model families, filtering logic, response structure, diagnostics, and caching. It does not contradict the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is detailed and well-organized with logical segments, but it is verbose and contains extensive technical specifics that could be condensed. It is not concise; every sentence earns its place but could be streamlined for agent efficiency.

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 (9 parameters, no output schema, multiple segments, caching), the description thoroughly explains the response structure, diagnostics, filters, and caching. It provides enough information for an agent to understand input, output, and behavior without needing additional documentation.

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

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

Schema coverage is 100% with clear descriptions for all 9 parameters. The description adds context by grouping them as 'tradeable-edge knobs' and explaining their purpose, but this extra value is marginal given the schema already does the heavy lifting. 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 explicitly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It clearly delineates the three opportunity segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing this tool from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 starts with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets', setting clear context. It details tradeable-edge knobs and filters but does not explicitly exclude alternatives or state when not to use this tool vs siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context about snapshot caching (gaps mean no scan) and response behavior (expired items, decay calculation). No contradiction with annotations.

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

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

The description is well-structured with the core purpose front-loaded, followed by response details and limits. It is lengthy but each part adds value; minor redundancy in default values 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?

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates with field details) and mentions limits (snapshot TTL, decay from daily closes). This is sufficient for an analysis 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 input schema already describes both parameters with full coverage. The description repeats defaults and adds minor context ('lookback', 'snapshot family'), but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on time-series analysis and decay.

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

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

The description explains when to use the tool (e.g., comparing fresh vs. old edges) and details the response structure (tracked[], expired[], snapshot_dates[]). It includes limits like snapshot TTL and decay calculation method, but lacks explicit alternative tools for different needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is clearly non-destructive. The description adds extensive behavioral context: it performs a read-only check, walks the order book ladder, returns verdicts like 'clean', 'degraded', 'cannot_fill', and warns about partial fill risks. 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 lengthy but well-structured: a clear one-sentence purpose, then REQUIREMENTS, then detailed breakdown of both modes, then usage guidance. Every sentence adds value, though some repetition could be trimmed. It is front-loaded with the most critical 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 lacking an output schema, the description fully compensates by detailing return values for both single-market and basket modes, including edge cases like thin legs and forced directional risk. It covers all behavioral nuances needed for an AI 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?

Schema coverage is 100%, so baseline is 3. The description adds significant value: interprets size_usd for buys vs sells and basket mode, explains side default roles, and clarifies market/event mode selection. This extra context justifies a 4, though it stops short of 5 because some details (e.g., exact format of market slug) are omitted.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly differentiates from sibling tools by specifying when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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

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

The description provides explicit usage guidance: when to use (before arb signals, trades above $500) and why (theoretical overround on thin books not capturable, partial basket fills cause directional risk). It also explains the two modes and their triggers.

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

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds extensive behavioral details: conditions for compatibility_warning, temporal alignment checks, and skipped cross-type/subtype counters. It clearly explains edge cases and data caveats, exceeding what annotations provide.

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

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

The description is dense but efficient, front-loading core purpose and modes. Every sentence adds context, though the length might be slightly overwhelming. No redundancy; structured with clear sections for modes, response, and safety fields.

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 response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counts). It covers edge cases and real-world rarity, making it complete for a tool with moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by listing valid topic values, explaining that explicit tickers override mapped sides, and providing examples. It clarifies parameter interactions and usage patterns.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit parameters) and distinguishes from siblings like polymarket_arbitrage by focusing on a specific cross-venue 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 explains when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility_warning, implying they may not be tradeable. However, it does not explicitly contrast with alternative tools such as polymarket_arbitrage or bet_research.

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 as read-only and idempotent. The description adds important behavioral details: default limit of 50, max of 50000, and return structure of row objects keyed by field name.

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

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

The description is concise but packed with useful information. While a single paragraph, it is well-structured and front-loaded with the main purpose, with no wasted words.

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

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

Given 8 parameters and SoQL complexity, the description provides sufficient context: how to get field names, pagination limits, and example queries in the schema. Output schema absence is mitigated by explaining return structure.

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

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

Schema covers all 8 parameters with descriptions. The description adds value by explaining the Socrata 4x4 code, SoQL clause syntax, and the default limit, going beyond the schema.

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

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

The description clearly states the tool queries rows from a dataset using SoQL, distinguishing it from siblings like search_datasets and dataset_columns.

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 advises using dataset_columns first to learn field names and explains the purpose of each SoQL clause, providing clear context for when to use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier (anonymous IP, BYO key hash, account ID) and pairing semantics. No contradiction.

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

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

Three sentences, each substantive: core function, use case, scope/relationships. 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?

Covers both modes (retrieve by key, list all), scope, and sibling relationships. Annotations cover safety. No gaps for a simple 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 100% with description for 'key'. Description adds behavior: omit to list all keys. Adds value beyond schema.

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

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

The description specifies the verb 'retrieve' or 'list', resource 'saved values/keys', and scope 'scoped to your identifier'. It clearly distinguishes from siblings remember and forget.

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

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

States when to use (look up context without re-deriving) and when to omit key (list all keys). Mentions pairing with remember/forget. No explicit when-not-to-use, but sufficiently 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?

Description contradicts annotation readOnlyHint: true by describing mark_read functionality that modifies feed state (flags events as read). Annotation contradiction detected.

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

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

Concise multi-sentence description with no fluff; front-loaded with purpose, followed by key fields, filtering, mark_read behavior, and alternative endpoint. Every sentence adds value.

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

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

No output schema, but description lists returned fields (source, citation_uri, raw payload). Parameter count 5, all documented. Sibling tools context understood. Complete for an agent to 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?

All 5 parameters have descriptions in schema (100% coverage), and description adds contextual examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains effects (mark_read flagging behavior, unread_only filter).

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

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

Clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields. Differentiates from sibling tools like list_subscriptions by focusing on recent alerts retrieval.

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: mentions polling works fine, offers alternative endpoint for scripts/dashboards, and explains filtering options and mark_read effect.

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?

Behavioral details are well-articulated: read-only, idempotent, non-destructive (consistent with annotations), plus source-specific behaviors like PatentsView soft-fail and structured return format with citation URIs. No contradiction.

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

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

The description is front-loaded with example queries and is efficiently structured. Every sentence earns its place, covering purpose, inputs, behavior, and alternatives without redundancy.

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

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

Despite no output schema, the description adequately explains the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). It covers all essential aspects for correct tool selection and invocation.

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

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

With 100% schema coverage, the description adds meaningful usage context: examples for 'since' (ISO date vs relative), typical value ('30d'), and explanation for 'value' (ticker or CIK). It also notes 'type' is limited to 'company'.

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

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

The description explicitly states that the tool provides a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. Example queries and differentiation from entity_profile make purpose 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 provides explicit when-to-use guidance (e.g., 'Use entity_profile instead when you want the static profile') and explains source fallback behavior (GDELT preferred, GNews on rate-limit). It also specifies input formats and supported entity types.

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 idempotentHint=true and destructiveHint=false, making the tool safe to repeat. The description adds meaningful context beyond annotations: scoping by identifier, persistence rules for authenticated vs anonymous users, and pairing with recall/forget. No contradiction.

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

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

The description is five sentences, front-loaded with the main purpose, and each sentence adds value (purpose, when-to-use, persistence, companion tools). It is efficient but not perfectly minimal; slight room for tightening.

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 covers purpose, usage, behavior, and companion tools. It explains key-value storage and scoping. It lacks explicit info on overwrite behavior or size limits, but idempotentHint implies safe overwrite. Mostly complete.

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

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

Schema coverage is 100% with both key and value well-described. The description adds example values (ticker, address, preference) but does not provide additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Save data' and the resource 'the agent will need to reuse later'. It distinguishes the tool from siblings by naming companion tools (recall, forget) and providing examples of what to store (ticker, address, preference, research subject).

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

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

The description explicitly says when to use: 'when you discover something worth carrying forward'. It also explains the tool's scope and persistence rules (authenticated persistent, anonymous 24h). It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: internal multi-endpoint cascading, source-labelled identifiers, explicit `unresolved` fields, and graceful degradation when GLEIF/OpenFIGI are unavailable. This goes beyond the annotations to set accurate 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?

The description is fairly long but well-structured with example queries and a SUPPORTED TYPES section. Every sentence contributes useful context, though it could be tightened slightly to reduce verbosity without losing important details.

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

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

Given there is no output schema, the description does an excellent job of explaining return behavior: identifiers with source labels, unresolved entries, and citations for drug lookups. It also covers failure scenarios (graceful degradation), making it complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds substantial meaning by providing concrete examples (AAPL, CIK, ozempic), explaining the 'cross-source identity spine' for companies, and specifying return components (RxCUI, ingredient, brand) per type, which is far more informative than the schema alone.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also provides concrete example queries (e.g., 'What's the ticker for…') and distinguishes itself from siblings by being the go-to for name-to-ID conversion, covering company and drug types.

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 to 'Use FIRST whenever you have a name but need an ID,' giving clear priority over alternatives. It also details supported types, accepted input formats (ticker, CIK, name, brand/generic), and notes graceful degradation for enrichment sources, making usage conditions explicit.

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, non-destructive behavior. The description adds that it internally calls ai_visibility_check for each entity and returns a ranked list. This aligns with annotations and provides useful behavioral context; no contradictions.

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

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

The description is two sentences: first states the core function, second provides a practical use case and output summary. It is front-loaded, concise, and every sentence is informative without being 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?

The tool has moderate complexity with 4 parameters and no output schema. The description adequately explains the aggregated ranking output (score, confidence, signal density). However, it omits potential errors from invalid API keys or empty results, which is acceptable given schema coverage.

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 semantic value by noting that the first entity is treated as the 'subject' for narrative, which is not in the schema. This qualifies as meaningful addition.

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 title and description clearly state that the tool compares AI visibility across multiple entities. It uses specific verb 'scan' and resource 'competitor AI presence', and distinguishes itself from siblings like ai_visibility_check by aggregating multiple probes.

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 concrete use case ('competitive AI-marketing audits') and implies it is for multi-entity comparisons. However, it does not explicitly state when to use the single-entity sibling ai_visibility_check instead, missing a clear 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 a single paragraph but well-structured, covering purpose, use cases, return format, ecosystem scope, and failure behavior. Every sentence adds value, though breaking into bullet points could improve readability slightly.

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

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

The description is comprehensive given the tool's complexity (composite, multiple services, partial failures). It explains the return format (summary block fields, per-advisory detail, links, alternative versions), ecosystem limitation, and graceful degradation without 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?

Input schema covers both parameters with 100% description coverage. The schema already describes 'package' and 'version' clearly. The description adds extra context (scoped packages accepted, default to latest) that enhances understanding, justifying a score slightly above baseline 3.

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

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

The description explicitly states the tool performs a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It clearly identifies the resource (npm package) and action (scan/check). The sibling tools are unrelated, so no confusion.

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

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

The description provides explicit use cases: 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes the ecosystem limitation ('NPM ecosystem only in v1') and directs users to alternative tools for other ecosystems.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds no behavioral contradictions and confirms read-only search behavior. It adds context about the data portal and result format, which is useful but not critical given the annotations.

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

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

The description is two concise sentences plus a list of topics and examples. It front-loads the core purpose. The list of topics is slightly verbose but adds valuable context. Could be slightly tighter, but overall 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 search tool with no output schema, the description fully explains what is returned (id, name, description) and provides domain context, example queries, and integration guidance. It is complete enough for an agent to use effectively without additional 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 description coverage is 100%; all three parameters (`q`, `limit`, `offset`) are documented in the schema. The description adds no new parameter-level details beyond schema. It adds context about the portal and id format, but that is not parameter-specific. 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 searches datasets on a specific portal (data.bts.gov) and returns a structured result (id, name, description). It distinguishes itself from sibling tools by mentioning how the id can be used with `dataset_columns` and `query_dataset`, and gives domain coverage (aviation, freight, etc.).

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

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

The description provides explicit guidance on using the returned ids with `dataset_columns` and `query_dataset`, and gives example queries and topics. It does not explicitly state when not to use the tool (e.g., for non-BTS data), but the context is sufficiently clear for an agent.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds valuable behavioral detail: embedding model (BGE-base-en), similarity (cosine), window size (500-char overlapping), and a 200K char cap with truncation behavior.

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

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

Description is about 4 sentences, front-loaded with main purpose, and every sentence adds value. No fluff.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores) and truncation behavior. For a tool with 3 well-documented parameters and rich annotations, this 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% with good descriptions for all three parameters. The description provides examples for query and states default limit (5) and max chars for text, but does not add significant new meaning beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with offsets and scores. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and highlighting use for large texts.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns relevant passages, offsets for verification) and suggests pairing with another 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 indicate mutable, non-destructive, idempotent behavior, and the description confirms this by stating subscriptions are persisted. It adds essential details like OAuth account requirement, delivery limits, and webhook signing, going well beyond the annotations.

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

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

The description is well-structured, front-loading the core purpose, then expanding on types and delivery channels. Every sentence provides necessary context without redundancy, making it both comprehensive and succinct.

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 (3 parameters, nested objects, no output schema), the description thoroughly covers subscription types, delivery options, account prerequisites, and operational constraints. It leaves no major gaps for an agent to infer.

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

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

The input schema covers 100% of parameters with descriptions, but the description adds significant value by providing concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topics) and delivery details (phone verification, webhook HMAC). This enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and subscription types.

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

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

The description provides explicit context for when to use the tool, requiring a Pipeworx OAuth account and detailing delivery channel constraints (e.g., SMS 10/day cap). It does not explicitly exclude use cases but the detail is sufficient for an agent to decide.

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, so the description doesn't need to repeat those. It adds useful context: the tool is an onboarding entry point, draws from a live catalog, and returns example questions with tool shapes. No contradictions with annotations.

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

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

The description is front-loaded with example queries and a clear statement of purpose. It lists categories and behavior in a structured way. While somewhat long, every sentence adds value, and the information is well-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?

Given one optional parameter, no output schema, and numerous sibling tools, the description is highly complete. It explains the tool's purpose, usage, return content, and context for when to call it first. Without an output schema, it adequately describes what to expect.

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

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

Schema coverage is 100% (only 'topic' parameter), so baseline is 3. The description adds meaning by listing example values (finance, pharma, etc.) and explaining that omitting topic gives a full spread. This goes beyond the schema's description.

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

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

The description states that the tool returns category-bucketed example questions to help users understand what to ask Pipeworx. It lists specific categories (finance, pharma, etc.) and explains the optional topic parameter. This clearly distinguishes it from sibling tools like ask_pipeworx or entity_profile.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and mentions learning how to call meta-tools like ask_pipeworx, entity_profile, compare_entities. This provides excellent when-to-use and when-not-to-use guidance.

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

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

Annotations provide idempotentHint and destructiveHint; description adds that the row is deactivated but not deleted, preserving historical events. 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?

Two concise sentences front-loading the main action, with no extraneous information.

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

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

Given the simple tool (single parameter, no output schema), the description fully covers purpose, ownership, and behavioral consequences.

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 parameter 'id' is self-explanatory with its schema description. The tool description adds no additional semantic value for the parameter.

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 resource ('by id'). It distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

It specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion). However, it does not mention when not to use or compare to alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it explains the exact meaning of 'could_not_verify' (the check did not happen and must not be treated as evidence), 'unsupported' (no source covered), and the structured vs. grounded pipeline routing. It also discloses the return format (verdict, actual value, citation, reasoning). This goes far beyond the read-only/idempotent annotation hints and proactively prevents misuse.

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 trigger phrases and organized logically: it states the purpose, details the two pipelines, lists the output, and gives important caller caveats. Although it is longer than typical descriptions, every sentence carries unique information—the trigger examples, tolerance guidance, and error semantics all earn their place. No padding detected.

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

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

Given the complexity of the tool (two processing paths, six verdicts, error handling) and the absence of an output schema, the description thoroughly covers what the agent needs to invoke the tool correctly and interpret results. It explicitly explains the distinction between 'could_not_verify' and 'unsupported', states the citation mechanism, and notes that it consolidates multiple sequential calls. Nothing critical appears 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 both parameters have descriptions, so the schema already documents them. The description adds extra semantic value, especially for tolerance_pct, by explaining how the implied tolerance default works and suggesting 1–2% for hallucination detection. This guidance is useful beyond the schema's basic description.

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

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

The description clearly defines the tool's function as natural-language claim verification against authoritative sources, with specific verbs like 'verify' and 'check'. It includes trigger phrase examples and describes the two processing paths (SEC EDGAR for company-financial claims, grounded pipeline for others). However, it does not explicitly distinguish itself from sibling tools such as ask_pipeworx_grounded or deep_research, so it lacks explicit sibling differentiation.

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 a clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs. other claims and mentions it replaces 4–6 sequential calls, implying efficiency benefits. However, it does not explicitly name alternatives or state when NOT to use this tool, leaving room for ambiguity with sibling tools.

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