Country State City

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds that the tool returns per-model {score, confidence, signals, raw_response} + combined view, and that _apiKey is passed to Anthropic. It does not mention rate limits or cost, but adds meaningful context beyond annotations.

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

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

The description is a single paragraph that efficiently conveys purpose, usage, return format, and parameter nuances. It front-loads the main action. A more structured format (e.g., bullet points for returns) would improve readability, but current version is not verbose.

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

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

Given 4 parameters and no output schema, the description covers return format sufficiently, explains the apiKey flow, and specifies default model. Minor omissions like error handling or timeout behavior exist, but the essential information for correct invocation is present.

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 parameter descriptions. The description supplements by explaining the default model, the role of _apiKey, and gives examples for entity and context. This adds value beyond the schema, raising it above the baseline of 3.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and returns visibility scores. It uses specific verbs like 'probe' and 'score', and names the resource. Though there is a sibling tool 'scan_competitor_ai_presence' that could overlap, the description does not explicitly differentiate, preventing a 5.

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

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

The description mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to provide _apiKey (for Anthropic) and defaults to Workers AI. However, it does not state when to avoid this tool or suggest alternatives like scan_competitor_ai_presence.

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. The description adds meaningful behavioral context: it routes questions to the right tool, fills arguments, returns structured answers with pipeworx:// citations, and states it works on every tier with one fast call. It doesn't contradict annotations but could add more about failure modes or ambiguity handling.

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 every sentence contributes value: it starts with the key directive, lists domains, provides examples, gives usage triggers, and explains when to use alternatives. It is well-structured and front-loaded, though a bit verbose in the middle. Overall it earns its length.

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

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

For a complex routing tool over thousands of sources, the description is comprehensive. It covers what the tool does, when to use it, examples, relationship to siblings, and even the return format (structured answer with citation URIs). No output schema exists, but the description sufficiently describes the response characteristic. It is complete enough for an agent to select and 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?

The input schema has 6 parameters, all aliases for the question string, with 100% schema coverage. The schema already explains that the question accepts query, q, prompt, text, input as aliases. The description adds example queries and clarifies the natural-language nature of the input, but doesn't provide additional parameter syntax or constraints beyond what the schema states.

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

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

The description clearly states the tool routes factual questions to the best of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It lists specific domains (SEC filings, FDA data, FRED/BLS, etc.) and gives example queries, making the purpose unmistakable. It also distinguishes itself from siblings 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?

The description explicitly says 'PREFER OVER WEB SEARCH' and instructs to use it for factual questions involving 'what is', 'look up', 'find', 'get the latest', etc. It provides clear alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is explicit when-to-use guidance with alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it is a full working router (not a fallback), current state (no active candidate), and that results are compared against the stable router to inform merges. This enriches behavioral understanding without contradicting annotations.

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

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

The description is somewhat long but informative, front-loading the beta nature and immediately clarifying equivalence with ask_pipeworx. Each sentence adds meaningful context (current state, usage guidance, and experimental purpose), so no content is wasted. Slightly over-wordy but well structured.

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

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

This is a complex tool acting as a universal router, yet the description provides essential context: identical scope, current inactive state, fallback is none (full working router), and evaluation purpose. Since there is no output schema, the reference to 'same response shape' as ask_pipeworx gives some context, though it would be stronger if it described what that shape entails. Overall, reasonably 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 all 6 parameters clearly documented as aliases for the required 'question' field. The description does not add parameter-level detail beyond saying it shares the same arguments as ask_pipeworx, which is a mild complement to the schema. Given the schema already fully explains parameters, 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 identifies this as a beta variant of ask_pipeworx, explicitly stating it is an identical universal router with the same tools, arguments, and response shape. It differentiates from the stable ask_pipeworx by noting candidate routing improvements, making its purpose specific and distinct.

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

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

The description provides clear usage context: use it exactly like ask_pipeworx when you want the newest routing. It implies the stable ask_pipeworx as the alternative, though it does not explicitly say 'do not use when stability is required.' The mention of comparing against the stable router gives a clear sense of when this experimental tool is intended.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the return shape, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the strict grounding principle ('using ONLY what the tool result contains'). It also notes the extra LLM call cost—behavioral context annotations do not provide.

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

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

The description is information-dense with clear internal structure: definition, process, return format, refusal modes, usage guidance, and cost tradeoff. Every sentence earns its place; there is no fluff or repetition. The length is justified for a high-stakes tool.

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

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

Even without an output schema, the description fully specifies return values, error/refusal semantics, example use cases, and the differentiating tradeoff vs ask_pipeworx. It covers all likely agent questions about when and how to invoke, making it self-sufficient.

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

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

Schema description coverage is 100%: all six parameters are aliases for the same 'question' field and are documented with descriptions. The tool description adds no further parameter-specific detail, which is acceptable because the schema already carries the full semantic load. Hence 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains the full process: routing, fetching, and extracting from tool results only. It explicitly distinguishes from sibling ask_pipeworx by adding grounded evidence and refusal behavior, making the tool's unique purpose unmistakable.

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

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

The description states exactly when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff (one extra LLM call), giving the agent clear decision criteria.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint=true, etc.). It explains market resolution, classification, fan-out, response shapes, resolver contract with confidence levels, parent event extraction, news fallback behaviors, safety short-circuits for low confidence or closed markets, wide-spread illiquidity handling, and cancellation rules. 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 long but front-loaded with the core purpose and usage. It efficiently packs many behavioral details into clearly separated sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value, though some details (e.g., candle-stick futures from 2026) could be streamlined. Overall, it is well-structured for the 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 the tool's complexity and lack of output schema, the description covers the return structure comprehensively (market, analysis, evidence, match confidence, parent events, news fields). It also documents error/edge cases (low confidence, closed markets, wide spreads). A minor gap is not enumerating all possible data sources, but the fan-out examples suffice.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mostly reiterates the parameter purposes from the schema. While the description provides examples of usage, it does not clarify parameter constraints or edge cases beyond what the schema already captures.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the inputs (market slug, URL, or question text) and explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which serve narrower purposes.

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 for when to use this tool ('Use for...'), giving clear context. However, it does not explicitly mention when not to use it or name alternatives among sibling tools, which would strengthen guidance. The examples effectively imply the tool is for comprehensive research, not quick checks or arbitrage.

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

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

Annotated as read-only and non-destructive. Description adds behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, results sorted by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

Description is packed with useful information but is slightly verbose. It front-loads common queries effectively. Could be shortened slightly without losing clarity, but still highly efficient.

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

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

Given the complexity (two entity types, multiple metrics, fiscal year handling), the description covers all essential aspects: data sources, sorting, citation URIs, and efficiency gains. No output schema, but return format is adequately implied.

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

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

Schema has 100% coverage; description adds meaning by explaining what each entity type pulls (financials vs. adverse events/trials) and the constraints on the values array (min 2, max 5). Also clarifies usage of tickers/CIKs vs. drug names.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using verbs like compare, and lists common user queries. It distinguishes from sibling tools by advocating preference over sequential single-pack lookups.

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

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

Explicitly tells when to use: for comparison queries like 'X vs Y', 'rank these companies', and 'head to head'. It strongly recommends this tool over alternatives (ALWAYS PREFER over sequential lookups) and provides examples.

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

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

Adds account/paid-tier requirements, decomposition/parallel routing, return packet shape with gaps[], contradiction scan, citation fetchability, semantic excerpting, latency—far beyond the readOnly/openWorld/idempotent annotations. 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?

Long but information-dense; every sentence adds a distinct fact (e.g., account prerequisite, return shape, citation_uri rule). Slight redundancy around 'not open-web search' and repeated ask_pipeworx references, but acceptable given tool 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?

No output schema, and description fully explains return packet structure, gaps[], contradictions[], hop field, citation_uri, latency, and semantic excerpting. Complete for a complex research tool with two parameters.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds meaningful depth semantics (quick=3 facets, standard=5+gap recovery, thorough=8+lead chasing) and clarifies broad/multi-part question suitability, going beyond schema wording.

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

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

States 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with open-web search, distinguishing from ask_pipeworx sibling tool.

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

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

Explicitly says 'Best for broad/multi-part questions over structured data' and provides clear alternatives: single lookup use ask_pipeworx, breaking/current-news prefer ask_pipeworx, not signed in use ask_pipeworx. Also details depth-level use cases.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N tools with schemas and examples, ready to call directly, which provides useful context beyond annotations. 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 purpose, then lists domains, then describes output, then gives usage advice. Every sentence is necessary and well-placed, no redundancy.

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

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

Given the tool's role as a discovery tool among many siblings, the description covers purpose, usage, return value, and guidance. No output schema exists, but the return format is described in words. It is complete enough for an agent to select and 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 coverage is 100% with examples, so baseline is 3. The description does not repeat parameter details but the schema and curated examples in the input schema clarify the query parameter and its aliases. The description adds value by mentioning the return format, keeping it concise.

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 'Find tools by describing the data or task' and lists many specific domains, distinguishing it from sibling tools by positioning it as a meta-tool for discovery. It also explicitly advises to call it first when many tools are available.

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: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by domains, and 'Call this FIRST when you have many tools available and want to see the option set'. This tells the agent when to use and implies not to use if the tool is already known.

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 safe, read-only, idempotent behavior. Description adds context: fans out across multiple sources, soft-fails for patents, returns specific data points.

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 example queries. Slightly verbose on patents sunset detail, but overall efficient and well-structured.

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

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

Covers all aspects: purpose, inputs, outputs, source details, fallback behavior. No gaps given no output schema.

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

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

Schema coverage is 100%. Description clarifies type is only 'company' for now, and value can be ticker or zero-padded CIK, not names—adding 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 provides a full cross-source profile of US public companies, listing specific data sources and outputs. It distinguishes from sibling tools like resolve_entity.

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

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

Explicitly advises when to use ('holistic view' queries) and when not (names only, requiring resolve_entity first), with example queries.

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

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

Discloses destructive nature ('Delete') consistent with destructiveHint annotation. Adds context about clearing sensitive data and pairing, though idempotentHint is not explained. Still, adds value beyond annotations.

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

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

Two sentences, front-loaded purpose, no unnecessary words. 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 deletion tool with one parameter and no output schema, the description fully covers purpose, usage conditions, and relationships to sibling tools.

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 one parameter 'key' described as 'Memory key to delete.' Description adds no extra meaning beyond what schema provides, meeting 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?

Description clearly states 'Delete a previously stored memory by key,' specifying the verb and resource, and distinguishes from siblings like remember and recall.

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

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

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Mentions pairing with remember and recall, guiding the agent on alternatives.

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

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

The description adds behavioral details beyond the annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. The annotations already indicate a read-only, idempotent operation, and the description aligns with no contradictions.

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

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

The description is concise and front-loaded: first sentence states the core function, then gives a brief process, output format, and use cases. Every sentence adds value without redundancy.

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

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

The tool is simple with strong annotations and full schema coverage. The description covers purpose, process, output, and use cases, making it sufficient for an agent to use without additional context.

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

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

The input schema has 100% description coverage for both parameters ('url' and 'max_links'), so the description adds minimal extra meaning beyond what the schema provides. It does not elaborate on parameter formats or constraints.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the exact verb and resource ('generate', 'llms.txt file'). It differentiates from sibling tools by its unique function, as no other sibling tool generates llms.txt files.

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: getting a client's site indexed by AI, drafting for a project, or auditing competitor sites. It gives context for when to use the tool but does not include when-not-to-use or alternative tools.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds filtering behavior and examples but doesn't address rate limits, authentication details, or response format beyond 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?

Two sentences with no wasted words. The first sentence states the purpose and filtering capability; the second provides parameter examples. Front-loaded and efficient.

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

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

For a simple read-only lookup tool with full schema coverage, annotations, and an output schema, the description is complete. It covers all necessary context: what the tool returns, required parameters, optional filters, and usage examples.

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 all three parameters. The description adds concrete examples (e.g., 'US', 'CA') that are not in the schema, providing practical usage context beyond the bare parameter names.

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

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

The description clearly states the tool retrieves cities for a country with optional state filtering, using specific verbs and resource types. It distinguishes itself from sibling tools like 'get_states' and 'list_countries'.

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 specifies required (country_code) and optional (state_code) parameters with examples (e.g., 'US', 'CA'). While it doesn't explicitly state when not to use or direct to alternatives, the context from sibling tools provides implicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond confirming it returns 'state names, codes, and types'. It is consistent with annotations and avoids 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 a single, efficient sentence that conveys all necessary information without any wasted words. It is well-structured and 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?

For a simple lookup tool with comprehensive annotations and an output schema, the description is complete. It specifies input (ISO2 code) and output (names, codes, types), and the tool's behavior is fully understood.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that country_code is an ISO2 code and mentioning the output fields (names, codes, types), 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 'Get all states or provinces for a country by ISO2 code' using a specific verb ('Get') and resource ('states or provinces'). It distinguishes from sibling tools like 'get_cities' and 'list_countries' by focusing on states/provinces.

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 specifies when to use the tool: to get states for a country by ISO2 code, with examples ('US', 'IN', 'BR'). It does not explicitly mention when not to use it or list alternatives, 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 provide readOnlyHint, idempotentHint, etc. The description adds behavioral context like returning ~250 countries and specific fields, which goes beyond annotations without contradicting them.

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

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

Two sentences with no waste. The first sentence lists the purpose and data, the second gives a typical use case. Front-loaded and efficient.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description is fully adequate. It explains the return fields and typical use, covering all necessary context.

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

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

Schema description coverage is 100% for the single parameter _apiKey, so baseline is 3. The description adds no extra meaning beyond what the schema already 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 clearly states the verb 'List' and resource 'countries', specifies exactly what data is returned (ISO codes, capitals, etc.), and distinguishes from sibling tools like get_cities or get_states.

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 like 'building dropdowns or validating country data', providing clear context for when to use. It does not explicitly mention when not to use, but the sibling tools are sufficiently different to avoid confusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds return fields (id, type, params, created_at, last_fired_at, fire_count). No contradiction.

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

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

Two sentences: first states purpose and output, second provides usage guidance. No redundant text; 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?

Given the tool has 1 optional parameter and annotations cover safety, the description adequately covers purpose, return fields, and use cases. Lacks detailed return schema but lists fields.

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

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

Schema coverage is 100%, so the schema fully documents the include_inactive parameter. The description adds no extra meaning beyond what the schema provides; baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb (list) and resource (subscriptions). It distinguishes 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?

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' It does not specify when not to use or name alternatives, but context is clear.

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

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

With all annotations set to false, the description carries the full burden of behavioral disclosure and delivers richly: it discloses rate limiting (5 per identifier per day), the claim_token workflow for later retrieval, and that the tool is free and excluded from quota. It also clarifies the two-mode behavior (filing vs. checking with claim_token), which is far beyond what annotations alone 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?

The description is six sentences and front-loads the core purpose, but includes secondary details like roadmap impact and digest cadence that are informative yet slightly beyond the essential usage guidance. Still, every sentence adds value and none are redundant.

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

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

There is no output schema, so the description appropriately explains the claim_token return value and how to follow up on a filed report. Combined with schema-level details, it leaves no operational ambiguity for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter-level nuance. It explains the claim_token parameter's role in reading prior feedback and instructs users to avoid pasting end-user prompts into the message parameter, which goes beyond schema boilerplate.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource framing that immediately identifies the tool's purpose. It also distinguishes itself from sibling research/query tools by clearly positioning itself as a feedback channel specific to 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 explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and when not to use it (feedback about non-Pipeworx MCP servers), directing users to file elsewhere. It also provides clear scope guidance: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond annotations: no PII, derived from CF analytics-engine, cached 5min-1h depending on window, and returns specific fields (pack, tool, count). This fully discloses behavior.

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

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

The description is exceptionally concise: three sentences plus a bullet list of use cases. Every sentence adds value, no fluff. Front-loaded with the core purpose, then expands on use and implementation details.

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

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

For a simple tool with one optional parameter and no output schema, the description is thorough: it states the return type (top tools, packs, volume), use cases, data source, privacy, caching behavior, and window interpretation. Nothing essential is missing.

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

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

Schema coverage is 100%; the only parameter 'window' has enum values described. The description adds meaning beyond the schema, explaining the trade-off between short and long windows. This provides pragmatic guidance.

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

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

The description clearly states it returns top tools, packs, and total call volume over recent windows. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trends and popularity.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical choices, and checking alignment with other agents' needs. It also explains window trade-offs ('shorter windows surface what's hot right now; longer windows show steady-state demand'). While it does not directly name alternatives, the context is clear and well-motivated.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and output structure. 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 well-structured, starting with the main purpose, then explaining each mode, and concluding with technical details. It is front-loaded with key information. However, it is somewhat lengthy and could be slightly more concise, especially the fill check section.

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

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

Given the tool's complexity (two modes, multiple checks, no output schema), the description fully explains the response structure (opportunities[] and partition_check fields) and edge cases (fill check, placeholder filter, similarity threshold). It covers all necessary context for an agent to use 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 by explaining the effect of no args, providing examples for event slugs and topic questions, and detailing the different behaviors for each mode (e.g., partition_check for event, cross-event scanning for topic).

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and details both event and topic modes. This distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk, which focus on different aspects.

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

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

The description explicitly states when to use no args (trending_scan), event (single-event partition_check), or topic (cross-event scan). It recommends event for a specific market and explains that cross-event mode catches patterns missed by single-event mode. It also advises not to trade when realizable_edge_pp ≤ 0.

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 read-only, idempotent, non-destructive. Description adds extensive behavioral details: caching, response structure (by_segment, diagnostics), edge calculation, slippage, tradeable-edge filters. 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?

Very detailed and well-structured, but overly verbose. Some information could be streamlined or moved to schema descriptions. The density of technical detail may overwhelm some agents.

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 fully explains the response format (by_segment, fed_candidates, diagnostics) and all edge calculations. Also covers caching and tradeable-edge knobs. Highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for several parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains why min_kelly doesn't filter partitions). This adds value beyond the schema.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with price. Specific verb 'scan' and resource 'Polymarket markets'. Differentiates from siblings by focusing on edge discovery for daily betting, but doesn't explicitly name alternatives.

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

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

Provides clear context for when to use ('what should I bet on today') and how it works. Describes three model families and constraints. Lacks explicit when-not-to-use or direct sibling comparisons, but the context is sufficient for most agents.

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 and idempotent. The description goes beyond by detailing the response structure (tracked, expired, snapshot_dates), explaining how decay_pp_per_day is computed, and noting that snapshots are written on cache-miss. It also clarifies that decay numbers are from daily closes, not intraday.

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 sections for purpose, response breakdown, and limits. It is concise yet thorough, though slightly lengthy. 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?

Despite lacking an output schema, the description thoroughly explains the response format (tracked array with fields, expired array with lifespan, snapshot dates). It covers the key elements needed for agent understanding.

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%. The description adds defaults for days (14, max 30, clamp 2-30) and window (default '1wk', options '24hr', '1mo'), which is valuable beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends and decay metrics.

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 implies when to use it (e.g., assessing edge age and decay) and provides limits (60-day TTL, snapshot gaps). It does not explicitly state when not to use it or name alternatives, 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds behavioral context: walks the ladder, returns specific fields like verdict, profit_usd, thin_legs. It warns about forced directional risk and partial fills. No contradictions with annotations. Could mention any rate limits or data freshness, but otherwise comprehensive.

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 relatively long but well-structured with capitalized mode headers (SINGLE-MARKET, BASKET) and explicit use-case guidance. It front-loads the core purpose. Every sentence adds value, though some could be tightened. Overall effective for the 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 the tool's complexity (two modes, multiple return fields, no output schema), the description is thorough. It covers inputs, modes, defaults, outputs (including verdict, capture_ratio, thin_legs), and practical risks (partial fills, directional risk). No gaps remain for an agent to understand correct invocation.

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

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

Schema description coverage is 100%, so baseline 3. However, the description adds significant meaning beyond the schema: explains single-market vs basket mode, default side logic, interpretation of size_usd (max spend vs target proceeds vs settlement notional). This elevates clarity beyond 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 defines the tool's purpose as a realizable-vs-theoretical edge check against CLOB order-book depth. It distinguishes two modes (single-market and basket) and states the verb 'check'. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills lead to unhedged directional positions) and provides requirements (one of market or event).

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details that the tool checks bet shape equivalence, alerts via compatibility warnings, and indicates temporal alignment. It explains why some pairs yield no arb, covering behavioral traits thoroughly.

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, starting with the core function and then detailing modes, response fields, and safety warnings. Every sentence adds value; minimal redundancy, though slightly verbose for a simple tool.

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

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

Given the complexity of the tool (multiple modes, safety fields, potential mismatches), the description is complete. It covers all response components, edge cases, and limitations without requiring an output schema. No critical gaps.

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

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

With 100% schema coverage, the description adds significant value by explaining the two modes (topic vs explicit), listing all 10 topic shortcuts, and stating that explicit tickers override the topic mapping. This enriches the schema definitions.

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 as computing cross-venue spread between Kalshi and Polymarket for the same event. It states two distinct modes (topic shortcuts and explicit tickers) and what the response contains, distinguishing it from related 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 tells when to use the tool (to compare prices across venues) and when not (when compatibility warnings appear or temporal alignment is false). It warns that real spreads are rare and explains how to interpret safety fields, providing comprehensive usage guidance.

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

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

Annotations already declare safe read-only behavior; description adds scoping detail (identifier-based) without contradicting annotations.

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

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

Three concise sentences, front-loaded with main purpose, 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?

Simple tool with one optional parameter, no output schema needed; description fully covers use cases, scoping, and companion tools.

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

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

Schema covers 100% of the single parameter; description adds value by explaining the dual behavior of retrieving a specific key vs. listing all when 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?

Clearly states the tool retrieves a value by key or lists all keys, distinguishing it from sibling tools like remember and forget.

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

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

Explicitly describes when to use (look up stored context) and pairs with remember/forget, but does not state explicit when-not-to-use scenarios.

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 and idempotentHint. The description adds valuable context: that each alert carries source, citation_uri, and raw payload, and explains mark_read behavior. 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?

Concise 4-sentence description, front-loaded with main purpose. Each sentence adds meaningful information with no redundancy.

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

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

Comprehensive for a read-only tool with good annotations: explains return value structure, filtering, mark_read side-effect, and alternative access endpoint. No output schema, so return value explanation is sufficient.

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

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

Schema coverage is 100% (baseline 3). Description adds semantic info for type (example 'sec_8k'), since (ISO timestamp), and mark_read (flags read). Does not describe limit or unread_only, but adds value beyond schema for key parameters.

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 pulls fired events from the subscription feed, a specific verb+resource. It distinguishes from siblings like 'list_subscriptions' which list subscriptions, not alerts.

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

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

Provides clear usage context: filtering by type and/or since, mark_read behavior, and mentions polling works. Also notes an alternative HTTP endpoint for scripts/dashboards, but does not explicitly exclude cases or compare with all siblings.

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

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

Beyond annotations (readOnly, idempotent), the description details fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and the inclusion of citation URIs. No contradiction with annotations.

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

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

The description is well-structured and concise, with every sentence providing necessary information. It covers purpose, usage, parameters, and disambiguation without redundancy, making it easy for an agent to parse.

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

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

Given the tool's complexity (multiple sources, fallback behavior, flexible date input) and the absence of an output schema, the description adequately explains the return structure (changes grouped by source, total_changes count, citation URIs) and directs to entity_profile for alternative needs.

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 adds significant value by explaining acceptable formats for 'since' (ISO date or relative shorthand) with examples, and clarifying that 'value' accepts tickers or CIK numbers. It also notes that 'type' currently only supports '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 clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call', listing specific data sources and example queries. It explicitly distinguishes from the sibling tool entity_profile, ensuring the agent can correctly differentiate.

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 examples ('What's new with X', 'latest on Y') and when-not-to-use by directing to entity_profile for static profiles. This clear guidance helps the agent select the appropriate 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?

Adds key behavioral details beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour TTL for anonymous sessions. No contradiction with annotations.

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

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

Four sentences, each earning its place: main purpose, usage guidance, storage details, and pairing with siblings. Front-loaded with core action.

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

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

For a simple write-only tool with two parameters and no output schema, the description covers purpose, usage, storage behavior, and lifecycle. 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?

Input schema covers both parameters fully (100% description coverage). Description reinforces 'key-value pair' but adds no new parameter details beyond schema examples.

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

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

Clearly states the verb 'save', resource 'data', and scope 'across this conversation or across sessions'. Distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall/forget. Lacks explicit 'when not to use', but usage context is well-defined.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it cascades through multiple endpoints, degrades gracefully (LEI/FIGI enrichment falls back to EDGAR), labels identifiers with source, and explicitly states unresolved identifiers under 'unresolved' rather than omitting them. This goes 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 long but well-structured: it opens with user-facing query examples, states the core action, then details supported types with inline examples and error-handling behavior. Every sentence adds substantive information about the tool's scope, outputs, or failure modes. It could be trimmed slightly, but it earns 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?

Even without an output schema, the description explains what the tool returns: canonical identifiers, source labels, and explicit unresolved entries. It covers both entity types, accepted input formats, degradation behavior, and the fact that it replaces multiple lookups. This is more than enough for an agent to understand the tool's full behavior and limitations.

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

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

Schema coverage is 100%, and the schema already describes both parameters. The description further enriches understanding by explaining what 'company' entails (CIK, ticker, LEI, FIGI, ownership) and giving concrete examples for 'value' (e.g., AAPL, 0000320193, ozempic). This adds semantic depth beyond the schema, though a bit more could be said about drug value formats.

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: resolving user-spoken names to canonical identifiers. It provides concrete query examples and explicitly distinguishes itself from siblings by noting that it supplies IDs that other tools require as input, and says 'Use FIRST whenever you have a name but need an ID.'

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when to use the two supported types (company vs. drug) with input examples, and mentions that it replaces 2-3 manual lookups, giving clear context for when this tool is the recommended choice.

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. The description adds that it probes each entity with another tool and returns ranked output, but no additional behavioral details (e.g., rate limits, cost, or time impact) beyond what annotations cover.

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

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

The description is a single paragraph of four sentences, front-loaded with the core purpose. It is concise but could be slightly more structured (e.g., separate output details). No unnecessary 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 no output schema, the description adequately explains the return values (ranked list with score, confidence, signal density). It does not cover edge cases like error handling or parameter interactions, but overall it is sufficient for this 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 description coverage is 100%, so the baseline is 3. The description does not elaborate on parameter details beyond what the schema already provides; it only mentions entities and context in passing.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks, and returns a ranked list with scores. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-marketing audit context and use of ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example. It implies usage for multi-entity comparison but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single-entity checks.

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

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. 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 the core purpose and efficiently conveys guidance, return details, limitations, and behavior. While dense, every sentence is meaningful; could be slightly more concise but current length is acceptable.

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 lists return fields (summary block, per-advisory detail, links, alternative versions). It also covers edge cases (NPM-only v1, partial failures) and implicit requirements (network access). Complete for a 2-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted for 'package' and that 'version' defaults to latest when omitted. This justifies a score 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 tool's purpose: a composite check for evaluating npm packages across deps.dev and bundlephobia. It uses specific verbs ('scan') and resources ('dependency') and distinguishes itself from siblings like 'scan_competitor_ai_presence' by its unique function.

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 guides when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem limitations and alternatives (deps.dev:version for non-NPM).

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 details beyond annotations: explains embedding model, window size, character cap (200K) with truncation and flagging, and that each passage includes an offset for verification. No contradiction with annotations.

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

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

The description is concise (~100 words) and well-structured: starts with purpose, then usage guidance, then technical details. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers return values (top-N passages, offsets, scores), truncation behavior, and integration with siblings. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, providing baseline 3. The description adds examples for query and extra context for text (e.g., SEC 10-K body), enhancing usability without repeating schema details.

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 within a provided text, returning top passages with offsets and scores. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining the pairing and use case for large records.

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

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

The description explicitly advises using this tool when the record is too large for the prompt, thereby saving context. It mentions pairing with ask_pipeworx_grounded and technical caps, but does not explicitly list when not to use it.

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

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

The description discloses behaviors beyond annotations: requires Pipeworx OAuth account (not anonymous/BYO), SMS cap of 10/day, webhook auto-disable after 10 failures, and webhook signing secret returned once. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

The description is front-loaded with the core action, then prerequisites, then type details, then delivery channels. Every sentence provides necessary information without fluff. It is well-structured for an agent to parse.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is highly complete. It covers types, parameters, delivery options, prerequisites, rate limits, webhook signing, and auto-disable behavior. The absence of output schema is compensated by mentioning the return of subscription id and webhook secret.

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 meaning: explains the first three enum values with examples (sec_8k, polymarket_edge, fred_series) and provides detailed usage for delivery channels (email, sms, webhook) including constraints and webhook HMAC verification. However, two enum values (patent_grant, clinical_trial) are not described in the description, only in schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns a subscription id. This distinguishes it from sibling tools like list_subscriptions (listing) and unsubscribe (removal).

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

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

The description provides clear context on when to use (creating subscriptions) and includes prerequisites (requires Pipeworx OAuth account) and type-specific details. However, it does not explicitly mention when not to use or direct to alternatives, though the purpose is self-evident given sibling names.

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. Description adds valuable context: output structure (category-bucketed example questions with tool+argument shapes), that it draws from a live catalog, and that it can be called with no arguments. 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?

Somewhat long but front-loaded with common user queries, then explains output and usage. Structured logically. Could be slightly tighter but 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?

With no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shapes). Covers the main use case, parameter, and onboarding purpose. No major gaps.

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

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

Schema coverage is 100% with description for the topic parameter. Description further explains the topic parameter with examples ('finance', 'pharma') and the effect of omitting it ('full spread'). Adds 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 uses a specific verb ('returns category-bucketed example questions') and identifies the resource ('Pipeworx capabilities'). It distinguishes from siblings like ask_pipeworx by focusing on onboarding and discovery of what to ask.

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 to use this tool FIRST when unsure of Pipeworx's capabilities or to learn how to call meta-tools. Provides context for the optional topic parameter but lacks explicit when-not-to-use instructions.

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

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

The description discloses that the row is deactivated, not deleted, and historical events remain available via recent_alerts. This adds value beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by clarifying the non-destructive nature.

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

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

Two sentences, front-loaded purpose, then constraints and side effect. No wasted words; 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 tool with one required parameter and no output schema, the description covers purpose, constraints, and data lifecycle (deactivation, not deletion). It references a sibling tool (recent_alerts) for historical access, making it complete.

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

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

Schema coverage is 100%, and the description adds that the id is a uuid returned by subscribe, which provides semantic context linking to the sibling tool. This is helpful beyond the schema's simple type 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 states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

It provides context by stating ownership enforcement (can only cancel own subscriptions) and that the id comes from subscribe. However, it does not explicitly mention when not to use this tool versus alternatives like forgetting or deactivating through other means.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing internal behavior: structured SEC EDGAR + XBRL path for company-financial claims, grounded pipeline for others, exact percent-delta math, and the meaning of each verdict. Critically, it clarifies the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source), which is essential for correct interpretation. 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?

Although the description is long, every sentence adds value. It is front-loaded with example queries and a clear purpose, followed by routing details, return values, and caveats. The structure is logical and the length is justified given the tool's complexity (two pipelines, multiple verdicts, error semantics). No filler or redundancy.

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

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

The description is comprehensive for a complex claim-verification tool with no output schema. It covers input semantics, processing steps, return values (verdict types with meaning), citation format, and error handling. It also provides usage guidance for two distinct claim categories, making it complete for the 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 each parameter having a description. The tool description enhances this by providing concrete example claims, explaining that tolerance_pct overrides the implied tolerance, and giving a specific use case (1–2 for hallucination detection). This adds meaning beyond the schema's basic descriptions.

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

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

The description states the tool performs natural-language claim verification against authoritative sources, with examples like 'fact check' and 'verify the claim that…'. It clearly distinguishes itself from generic query tools by focusing on fact-checking and even outlines two distinct verification paths (SEC EDGAR fast path vs. grounded pipeline), setting it apart from sibling tools.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates use cases for company-financial claims vs. other factual claims, explaining the routing logic. While it doesn't mention exclusions, it gives clear context and even notes it replaces multiple sequential calls, which helps the agent select this tool over alternatives.

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