Boi Il

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: probing multiple LLMs, scoring details, that Anthropic requires a BYO key and direct payment, and the return structure (score, confidence, signals, raw_response per model plus combined view). No contradiction with annotations.

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

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

The description is a single paragraph of three sentences, front-loaded with the core function, followed by the key behavioral option (Anthropic), and ending with return structure and use cases. Every sentence adds new information with no fluff.

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

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

Despite no output schema, the description documents the return format ('per-model {score, confidence, signals, raw_response} + a combined view') sufficiently for the tool's complexity (4 parameters, no enums or nested objects). Combined with the schema, an AI agent has all needed information 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 each parameter described. The description enhances understanding by giving concrete examples (e.g., entity: 'Pipeworx', context: 'Boston restaurant') and explaining the default model and the optional Anthropic probe via _apiKey, which provides practical usage guidance beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model, with specific verb 'Probe' and resource 'LLMs'. It distinguishes its purpose from siblings by mentioning AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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

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

The description lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the default model vs. Anthropic with a key, but does not explicitly state when not to use or compare to alternative sibling 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 the tool read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context: it routes to one of 5,743 tools across 1,500 sources, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is a single fast call. It could disclose more about response variations or edge cases, but it is transparent about the core behavior.

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

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

The description is long but dense and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). The examples and escalation paths earn their place, though there is slight redundancy around it being the default entry point. Overall it is structured and readable for an agent.

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

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

For a tool with a single natural-language input, the description covers the full context: what domains it handles, what query patterns to use, concrete examples, how it differs from alternatives, and what the answer looks like (structured answer with citation URIs). No additional information is needed for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the question parameter is already well documented with aliases. The description adds value beyond the schema by clarifying the kinds of natural-language queries that work ('what is', 'look up', 'current', etc.) and by giving concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K', which helps an agent shape the input appropriately.

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

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

The description clearly states the tool's function: it answers factual questions by routing them to the appropriate one of thousands of verified data tools and returns a structured answer with citation URIs. It also differentiates itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell what this specific tool is for.

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 when-to-use guidance: prefer over web search for factual, current, or historical data; use as the default entry point for most questions. It also names specific alternatives for escalation: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, with a note that breaking news is already handled here.

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

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

Beyond the annotations, the description discloses critical behavioral traits: candidate improvements are enabled live only when under test, no candidate is currently active, its behavior is currently identical to ask_pipeworx, and it does not fall back to another tool—it is a full working router. This gives the agent an accurate model of what to expect now and later.

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 mostly efficient and front-loaded, with the primary identity stated first. Each sentence adds information about the beta status, live candidate behavior, usage guidance, and fallback behavior. Minor redundancy exists between "currently matches ask_pipeworx exactly" and "Use it exactly like ask_pipeworx," but overall the structure is tight.

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 complete enough for an experimental alias of an existing tool: it explains the beta nature, the current no-active-candidate state, the identical argument/response shape, and the comparison workflow. It does not independently document the underlying router's full behavior or response shape, but that is reasonably anchored through its reference to ask_pipeworx.

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

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

The schema already provides 100% coverage for all six parameters, including aliases and the primary `question` description. The description adds no additional parameter-level semantics; it only states that arguments are identical to ask_pipeworx, which is useful context but not needed to understand the parameters themselves.

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 immediately frames the tool as a beta variant of ask_pipeworx and concretely defines it as a universal router with the same 5,743 tools, arguments, and response shape. It clearly differentiates this tool from the stable ask_pipeworx by emphasizing the experimental edge and the live candidate routing mechanism.

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 instructs when to use this tool: "Use it exactly like ask_pipeworx when you want the newest routing." It also clarifies the current state (no active candidate) and contrasts with the stable router, giving the agent a clear decision rule for selection.

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 important behavior beyond the annotations: it extracts only from the tool result, returns a refusal instead of guessing, and enumerates concrete refusal reasons such as 'not_in_source' and 'data_truncated.' It also details the success and refusal response shapes, which is valuable since there is no output schema. The readOnlyHint and idempotentHint annotations are consistent with this non-mutating, grounded behavior.

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

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

The description is long but dense and front-loaded with the core purpose. Each clause adds a meaningful fact: extraction constraint, return shapes, refusal reasons, use cases, and cost/alternative. It is slightly longer than strictly necessary, but given the complexity and the absence of an output schema, the length is largely justified.

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 complete for a high-stakes question-answering tool. It explains the routing behavior, the grounded extraction guarantee, the exact success and refusal return formats, the failure categories, and the decision between this tool and ask_pipeworx. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%: all six parameters are aliases for 'question' and are well-documented in the schema. The description does not add new parameter semantics, but the schema already fully covers what the agent needs to know, so the baseline of 3 applies.

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

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

The description clearly identifies a distinct answer mode: it routes like ask_pipeworx but then 'EXTRACTS the answer using ONLY what the tool result contains.' The verb 'extracts' plus the resource 'answer' makes the purpose concrete. It also contrasts with ask_pipeworx, making the tool's unique function immediately clear.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the trade-off: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This fully routes the agent between the two siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds extensive behavioral details: low-confidence resolution short-circuiting (status:'low_confidence_match'), closed market handling, wide-spread tradeability flags, cancellation rule parsing, and fallback behaviors (GDELT 429s). This far exceeds what annotations provide and fully discloses operational nuances.

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 very long (multiple paragraphs) and densely packed with information. While every section (classifiers, fan-out examples, response shapes, etc.) adds value, the length hurts conciseness. The structure is somewhat organized with thematic breaks (e.g., 'CLASSIFIERS', 'FAN-OUT EXAMPLES'), but it could be more succinct without losing essential detail.

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 (classifiers, fan-out logic, response shapes, safety mechanisms, resolution details) and absence of an output schema, the description thoroughly explains return fields (result.market, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low confidence, closed markets, illiquidity). It is complete for an agent to understand 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 descriptions for all three parameters (market, depth, include_raw). The description adds significant meaning: examples of market input formats, explanation of depth values ('quick' vs 'thorough'), and the purpose of include_raw (compact vs full payloads). This goes beyond the schema to explain practical usage and trade-offs.

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 ('research') and resource ('Polymarket bet' via Pipeworx data). It explicitly lists use cases ('should I bet on X', 'what does the data say', 'is there edge'), which distinguishes it from sibling tools like polymarket_edges by focusing on a single-call research action. The purpose is unambiguous and well-scoped.

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

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

The description provides explicit usage contexts: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. It does not explicitly mention when not to use this tool or name alternatives (e.g., polymarket_edges), but the context is clear enough for an agent to decide. A mention of exclusions would elevate this to 5.

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

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

Annotations already show readOnlyHint, destructiveHint false. Description adds valuable behavioral details: returns currentExchangeRate (shekels per unit), currentChange, unit, and lastUpdate. Notes that unit may vary (JPY per 100). Contradicts no annotation.

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

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

Two sentences, front-loaded with core purpose and return fields. Second sentence adds a key behavioral note and examples. No redundancy, 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 single parameter with full schema coverage, no output schema, description covers all needed aspects: input, returns, and special behavior. Complete for an AI 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% and describes 'key' as 3-letter ISO code. Description reinforces that and adds semantic nuance: example keys and note about unit (JPY per 100). Adds meaningful context beyond schema.

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

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

Description clearly states it gets current Bank of Israel exchange rate for a single currency vs ILS, using 3-letter ISO code. It lists return fields and distinguishes from sibling 'boi_exchange_rates' (plural) which likely returns multiple rates.

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

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

Description specifies input as 3-letter ISO code and gives example keys. While it doesn't explicitly state when not to use, the sibling name 'boi_exchange_rates' implies that tool is for multiple currencies. Provides clear context for usage.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat safety. It adds useful context: returns one entry per currency, explains the 'unit' field and how to compute per-1 rates. This is sufficient disclosure beyond annotations.

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

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

The description is concise (three sentences) and front-loaded with the main purpose. It provides necessary detail without excess. Could be slightly more structured, but overall effective.

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

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

Given no parameters and no output schema, the description fully explains what the tool returns and how to interpret the fields (e.g., unit division for per-1 rate). It covers all relevant aspects 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?

The input schema is empty (no parameters), so the description has no parameters to explain. Baseline of 4 applies as no additional semantic burden. The description focuses on output structure.

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 'all current Bank of Israel representative exchange rates vs the Israeli Shekel (ILS)' and specifies the fields (currentExchangeRate, currentChange, unit, lastUpdate). The plural name 'boi_exchange_rates' versus singular sibling 'boi_exchange_rate' distinguishes its scope as a full-list 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?

The description says 'Use this for a snapshot of all available currencies,' which clearly indicates when to use it. However, it does not explicitly mention when not to use it (e.g., for a single currency, use the singular sibling tool). The sibling context helps, but the description could be more explicit.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds the specific return fields and scope, which is useful behavioral context beyond annotations. No contradictions.

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

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

Two sentences, no waste. Front-loaded with key purpose and scope. 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?

For a zero-parameter, read-only tool with no output schema, the description provides all necessary context: what it returns and its geographic scope. 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?

No parameters, so schema coverage is 100%. Description doesn't need to add param info. 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?

Clear verb+resource: returns the BOI policy interest rate. Specifies scope (Israel only) and return fields (currentInterest, nextInterestDate, lastPublishedDate). Distinguishes from sibling tools like boi_exchange_rate which are for exchange rates.

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?

No explicit when-to-use or alternatives mentioned, but scope (Israel only) implicitly guides usage. Sibling tools are about exchange rates, so context helps, but no direct comparison.

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 critical behavioral details: external API calls (SEC EDGAR, FAERS), fiscal year handling, sorting by primary metric, and citation URIs. 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?

Packed with information in ~100 words, front-loaded with examples. Could be slightly more structured, but every sentence adds value.

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

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

No output schema, but description covers return format (paired data, citation URIs, sorted results) and data sources. Lacks error handling or edge cases, but sufficient for most use cases.

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

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

Schema coverage is 100% with descriptions. The description adds significant meaning: explains data pulled per enum for 'type', provides examples for 'values', and documents behavioral nuances like off-calendar fiscal years.

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 comparisons of 2–5 companies or drugs, with example queries and specific data sources. It distinguishes itself from 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 prefers this tool over sequential lookups when comparing entities, and provides limits (2-5). Could be improved by naming 'entity_profile' as the alternative, but the guidance 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 establish readOnly, openWorld, idempotent, non-destructive behavior, but the description adds substantial behavioral context: parallel decomposition across 5,743 tools, gaps[] for unanswered facets, 'never invented' grounding, contradictions[] for standard/thorough, hop fields, always-fetchable citation_uri, semantic excerpting, and expected latency. None of this contradicts 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 the tool is genuinely complex and nearly every sentence carries distinct information. It is front-loaded with the critical account requirement and fallback tool. Slightly dense and repetitive in places, but efficient for the level of behavioral nuance it must convey.

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 research tool with no output schema, the description covers the input, output shape, auth requirements, cost constraints, alternatives, failure behavior, latency, and depth semantics. An agent has everything needed to decide whether to call the tool and what to expect from it.

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

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

Schema coverage is 100% and both parameters have descriptive entries, so the baseline is 3. The description adds extra meaning: the question parameter can be broad/multi-part because decomposition is the point, and the depth parameter is expanded with hop behavior and gap-recovery semantics beyond the enum descriptions. This is a meaningful but not transformative addition.

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

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

The description states a specific action and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in one call, and explicitly contrasts itself with open-web search. It also clearly differentiates from sibling ask_pipeworx by noting this is for broad/multi-part questions while ask_pipeworx handles single 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?

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data. It also gives when-not-to-use and alternatives: use ask_pipeworx for single lookups and for breaking/current-news topics, and use ask_pipeworx if not signed in. Account requirements and paid tier limitations are clearly stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to cover safety. The description adds that results are ready to call with examples, but does not disclose any behavioral traits beyond what annotations provide. No contradictions.

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

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

The description is a single paragraph that front-loads the purpose and then provides domain examples and usage guidance. It is fairly concise, though the list of domains could be trimmed slightly. 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 no output schema, the description thoroughly explains what is returned: tool names, descriptions, full input schemas with examples, and that each result is ready to call. This fully covers the agent's needs for a discovery 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 description coverage is 100%, so the schema is already detailed. The description does not add new parameter semantics beyond repeating the query and limit concepts. Baseline 3 is appropriate.

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

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

Description starts with 'Find tools by describing the data or task,' clearly stating the action and resource. It lists numerous domain examples (SEC filings, financials, FDA, etc.) and contrasts with siblings by highlighting that results include full schemas ready to call.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (i.e., when 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 already mark this read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: it fans out across specific sources, soft-fails on the USPTO PatentsView API sunset, treats empty sections as real 'no data,' and explains that private companies return resolved:false with a notes line. It also discloses that FDA products are limited to biologics, so absence of small-molecule drugs is expected.

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

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

The description is long, but every section earns its place given the tool's complexity: example phrases, source fan-out, per-section return semantics, failure modes, and input resolution rules. The core use case is front-loaded with query examples, and while dense, the semicolon-separated structure keeps related details grouped.

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 carries the full burden of explaining return values, and it does so comprehensively: it lists every response section, explains sources_used/sources_failed, covers expected empty results, and specifies the private-company failure path. An agent has enough context to call this tool correctly and interpret results without ambiguity.

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

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

The input schema already provides 100% coverage for both parameters, including the interchangeability of type and the accepted value shapes. The description adds value by giving concrete examples, emphasizing zero-padded CIKs, and noting name resolution via SEC EDGAR, but much of this repeats or lightly extends the schema. It is additive, but not transformative.

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 verb and resource: it produces a 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the exact data sources and explicitly frames itself against the alternative of chaining single-pack SEC/XBRL/news lookups, making it easy to distinguish from siblings like deep_research or 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?

It gives an explicit, imperative usage rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides clear conditions around accepted inputs, private-company resolution, and the meaning of empty sections. This is actionable guidance for when to invoke this tool versus a lookup chain.

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

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

Annotations provide safety hints; description adds context about clearing stale/sensitive data, which aligns with destructiveHint. No contradictions, and 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, zero waste. First sentence clearly states purpose, second provides usage context. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, when to use, and behavioral context adequately. Annotations fill remaining safety info.

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?

Single parameter 'key' is fully described in schema (100% coverage). Description does not add additional syntax or format details, meeting baseline but not exceeding.

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?

Clear verb 'Delete' and resource 'memory', with explicit mechanism 'by key'. Distinct from siblings 'remember' and 'recall' which handle storage and retrieval.

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

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

Explicitly states when to use: stale context, task completion, or clearing sensitive data. Mentions pairing with remember and recall, guiding appropriate usage.

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

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

The description discloses the tool's behavior beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This aligns with the idempotent and read-only annotations, adding process detail without contradiction.

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

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

The description is concise: two sentences with the core action and process, followed by a use-case list. Every sentence adds value, and key information is front-loaded.

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

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

Despite lacking an output schema, the description fully compensates by specifying the output format ('standard llms.txt markdown', 'single text blob ready to drop at site-root/llms.txt'). It covers purpose, process, output, and usage context comprehensively.

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

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

Schema description coverage is 100%, with clear parameter descriptions. The description adds limited additional parameter meaning, but it does contextualize the output format, which indirectly aids understanding.

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

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

The description clearly states the verb 'Generate', the specific resource 'llms.txt file', and the target 'any URL'. It distinguishes itself from sibling tools by specifying the exact output format and use cases for AI crawler indexing.

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

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

The description lists three explicit use cases (client site indexing, own project drafting, competitor auditing), providing clear guidance on when to use the tool. It does not explicitly exclude alternatives, but the context is sufficient for selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by listing the specific return fields (id, type, params, created_at, last_fired_at, fire_count), which is behavioral context beyond structured metadata.

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. First sentence states purpose and output, second sentence provides usage guidance. Concise 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 list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage. No gaps remain.

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

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

Schema coverage is 100% with a single parameter (include_inactive) well-described in the schema. The description does not add further meaning beyond repeating 'active subscriptions' and implying the parameter's effect. 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 and resource. It lists return fields but does not explicitly differentiate from sibling tools like 'subscribe' and 'unsubscribe', though the context implies listing.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit when-not-to-use alternatives, but the guidance is clear and actionable.

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

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

Annotations are all false and uninformative, so the description carries the full burden. It discloses rate limits (5 per identifier per day), free usage, no quota impact, and that the team reads digests daily. It also explains the claim_token return behavior without contradicting any annotation flags.

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 dense; every sentence adds value, and the purpose is front-loaded. It could be tightened or broken into bullets, but the structure logically flows from purpose to exclusions to follow-up and limits. Not wasteful.

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

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

For a feedback tool with 4 params (including nested object) and no output schema, the description covers all needed context: what to include, what not to include, account status, rate limits, and the claim_token follow-up mechanism. Nothing important 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 covers all parameters (100%), so baseline is 3. The description adds extra semantics: how to use claim_token with no other arguments, and the nuance of describing issues in terms of Pipeworx tools rather than pasting user prompts. This lifts it above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools like ask_pipeworx by scoping to Pipeworx tools and packs, and explicitly excludes other MCP servers.

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

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

Provides explicit when-to-use conditions (bug, feature/data_gap, praise) and a clear when-not-to-use with an actionable alternative ('file it with that server instead'). It also explains the claim_token flow for follow-ups, making usage contexts unmistakable.

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

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

Annotations already indicate safe read-only operation. Description adds valuable details: self-aggregating, no PII, caching behavior (5min-1h). No contradictions.

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

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

Four sentences with numbered use cases. Front-loaded with main action. No filler or redundant information.

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

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

Covers essential behavior and use cases. Lacks explicit output structure, but tool is simple and no output schema is expected. Acceptable for this complexity.

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

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

Schema covers 100% of parameters. Description adds context on what different window lengths surface (hot vs steady-state), giving extra meaning beyond schema.

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

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

Clearly states it returns top tools, packs, and total call volume over configurable windows. Distinguishes itself from siblings by focusing on trending data.

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?

Lists three explicit use cases: discovering hot data sources, confirming canonical choice, and checking alignment. Does not mention 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: fill check logic, semantic anchor for Jaccard similarity, partition filter for placeholder slugs, response structure, and handling of fill check results. 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 lengthy but well-structured with clear sections for each mode. Every sentence adds value, but it could be more concise. Front-loaded with main purpose.

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

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

No output schema, but the description fully explains the response structure (opportunities[], partition_check, fill_check details). Covers all input modes and edge cases like placeholder filtering and Jaccard similarity. Very complete for a tool with 2 optional params.

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%. The description adds beyond schema: accepted formats for event (URLs) and topic (seed question), and explanation of no-args mode. This provides rich semantic context for the agent.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and specifies the resource (Polymarket). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidelines on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It also explains why cross-event mode is beneficial and references sibling tool polymarket_fill_risk for custom sizing, providing alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds caching behavior ('Cached 1h at the KV level keyed on all knobs') and details response structure including diagnostics. 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 excessively long and dense, burying the core purpose under detailed explanations of model families and knob behavior. While well-structured in paragraphs, it violates conciseness by including excessive technical detail that could be streamlined or moved to a separate reference.

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 (9 parameters, no output schema), the description fully compensates by detailing response structure (by_segment, fed_candidates, _diagnostics), caching behavior, and tradeable-edge knobs. It provides everything an agent needs to understand how to interpret results and handle edge cases like empty segments.

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 description's primary value is in clarifying parameter semantics beyond the schema. It adds context for slippage_pp (e.g., 'zero trading fees but 20-50bp per trade') and min_kelly (e.g., 'half-Kelly fraction'). However, most parameters are already well-described in the input schema, so the description adds marginal value.

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

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

The description clearly states the tool scans Polymarket markets for discrepancies between Pipeworx data and market prices, explicitly targeting 'what should I bet on today' use case. It differentiates from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and segmenting opportunities into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT.

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

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

The description explains the tool is designed for discovering betting opportunities without paging hundreds of markets, and provides tradeable-edge knobs and diagnostics for why segments are empty. However, it lacks explicit guidance on when not to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description adds significant behavioral context beyond the annotations: it explains the structure of the response (tracked, expired, snapshot_dates), the meaning of decay_pp_per_day (signed by trade direction), and limitations like gaps in snapshot dates. Annotations already indicate read-only and non-destructive behavior, which aligns with the description.

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 question, but the RESPONSE section is detailed (tracked, expired, snapshot_dates) and could be shortened or moved to an output schema. It is informative but slightly verbose for a description.

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

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

Given no output schema, the description thoroughly explains return fields and limitations (TTL, decay computation). It is complete enough for an agent to understand the output and constraints, though it could mention error conditions or permissions.

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 value by clarifying 'window' as 'snapshot family' and providing default values. It slightly differs from schema on the 'days' range (says max 30 vs schema's clamp 2-30) but overall enhances understanding.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' based on daily snapshots, and answers a specific question about edge age and trend. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical persistence rather than current edges.

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

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

The description implies when to use by contrasting a fresh wide edge with a 3-week-old wide edge, indicating that this tool provides historical context not available elsewhere. It also lists LIMITS (e.g., 60-day TTL) that inform usage, but does not explicitly name alternative tools for comparison.

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, and idempotentHint. The description adds value by detailing the ladder-walking behavior, return fields (verdict, slippage, etc.), and risks for baskets (forced directional risk). No contradiction with annotations.

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

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

The description is long but well-structured, front-loading the purpose and then providing detailed mode-specific information. Every sentence adds value, though some redundancy could be trimmed. Still appropriately sized 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?

For a complex tool with no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs). Covers edge cases like partial fills and unhedged directional risk.

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). The description adds context for each parameter: explains default values, semantics of size_usd for single-market vs basket, and the difference between market and event parameters. 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 clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes. It is specific and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about when theoretical overround is not capturable, providing clear usage context.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral disclosure: compatibility_codes semantics, temporal_alignment null meaning, fees_note explaining gross vs net spreads, skipped leg counters, pairing_unverified caveats, and the fact that unclassified legs are never paired. This is well beyond what annotations provide and contains no contradiction.

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

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

The description is long, but the complexity of the tool justifies it. It is front-loaded with the core definition, then structured into modes, response format, safety fields, and caveats. Some redundancy and heavy capitalization reduce elegance, but the organization makes it scannable.

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 carries the full burden of explaining response semantics and edge cases. It covers leg prices, spread entries, per-entry flags, compatibility codes, temporal alignment, fees, skipped leg counters, and the meaning of nulls. An agent has enough to invoke the tool correctly and interpret its output safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description upgrades this by explaining how the two explicit parameters override topic-mapped sides, that both modes run the identical token-overlap matcher, and that no parameters are required but mode selection affects behavior. This adds practical meaning beyond the schema's field-level 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 identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question, which is a specific and unambiguous purpose. It does not explicitly name or contrast sibling tools like polymarket_arbitrage, but the venue pairing and 'same resolving question' scope make the intent clear.

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

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

The description gives clear context on when to use the tool: either via ten pre-mapped topic shortcuts or via explicit Kalshi ticker plus Polymarket slug. It also warns that many pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable. It stops short of explicitly saying when to choose this over sibling tools, but the mode guidance is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and explains the listing behavior when key is omitted. 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 three sentences, well-structured, and front-loads the core action. Every sentence adds value: retrieval vs listing, usage context, and scoping. 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 the simple one-optional-parameter tool with rich annotations, the description adequately covers purpose, usage, and scoping. It does not describe return format or error behavior, but no output schema exists to expect that. Minor gap in completeness for a production 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 description coverage is 100% and the schema already describes the 'key' parameter. The description reinforces the behavior when omitted ('omit the key argument') but does not add significant new semantics beyond what the schema provides. Baseline 3.

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

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

The description clearly states the verb 'retrieve' and the resource 'saved memory', distinguishes between retrieving a specific key and listing all keys with 'omit the key argument', and references companion tools remember/forget. This fully clarifies purpose and distinguishes from sibling tools like remember and forget.

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

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

The description tells when to use this tool: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also suggests pairing with remember and forget. However, it does not explicitly state when not to use it or mention alternative tools (e.g., deep_research) so it loses a point.

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), the description discloses that mark_read:true flags events as read, affecting future calls. It also describes returned fields (source, citation_uri, raw payload) and confirms the feed is persisted. This adds significant behavioral context beyond the structured annotations.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds necessary details (fields, parameters, polling guidance, alternative access). No superfluous content.

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

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

Despite lacking an output schema, the description explains the return structure (source, citation_uri, raw payload). It covers all parameters, explains the mark_read side-effect, and provides an alternative access method. For a read tool with good annotations, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that mark_read affects future calls, that since is an ISO timestamp, and that type filters by subscription type. However, limit and unread_only are not elaborated 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 pulls fired events from the subscription feed, specifying the resource (alerts) and action (pull recent). It distinguishes from siblings like list_subscriptions by focusing on event data rather than subscription metadata. The mention of filtering and marking read adds specificity.

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

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

The description explains when to use (get recent alerts) and provides context that polling works and an alternative endpoint exists for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds rich behavioral details: fans out to multiple sources, includes fallback logic, soft-fail for patents, and describes output format. No contradictions.

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

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

The description is a single focused paragraph that front-loads user intents, then efficiently covers sources, fallbacks, parameters, output, and sibling differentiation. 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?

With no output schema, the description adequately describes return structure (changes grouped by source, total count, citation URIs). It covers purpose, usage, parameters, behavior, and alternatives. Complete for a tool with 3 simple 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 coverage is 100%, but the description adds significant value: clarifies type enum only supports 'company', suggests typical values for 'since' ('30d'), explains value accepts ticker or CIK, and gives concrete examples.

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

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

The description clearly states the tool provides a change feed for a company in a recent window, using user intents like 'What's new with X'. It explicitly distinguishes from sibling 'entity_profile' by advising to use that for static profiles.

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

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

The description provides explicit when-to-use guidance, including preferred sources (SEC, GDELT) and fallback (GNews). It also contrasts with 'entity_profile' for static profiles, giving clear alternatives.

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

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

Annotations indicate idempotent and non-destructive. Description adds scope by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions, which is valuable 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?

Four sentences with clear front-loading: purpose, usage, behavior, and sibling references. No wasted words.

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

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

For a simple two-parameter storage tool with no output schema, the description covers purpose, usage, behavior, persistence details, and sibling integration. Complete and self-contained.

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

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

Schema coverage is 100% with descriptions for key and value. Description reinforces key-value pair concept and provides contextual examples like 'subject_property' and 'target_ticker', adding marginal value.

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

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

Description clearly states the tool saves data for reuse, with specific verb 'Save' and resource 'data'. It distinguishes from siblings like recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides examples. Mentions paired tools recall and forget for retrieval and deletion.

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, and the description does not contradict them. It adds significant behavioral detail beyond annotations: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit unresolved identifiers, returning figi_candidates on ambiguity, source labeling, and internal cascading across lookup endpoints.

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

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

The description is dense and long, but nearly every sentence carries operational value—usage directives, supported types, ambiguity handling, degradation behavior, and input caveats are all included. It is front-loaded with 'Use FIRST' and the core purpose. Slight verbosity in phrases like 'cross-source identity spine' keeps it from a perfect score.

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

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

Despite no output schema, the description thoroughly explains return contents: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, citation, source labels, unresolved identifiers, and figi_candidates. It also covers input formats, edge cases like non-US issuers and non-equity instruments, and failure behavior. An agent has everything needed to call it correctly.

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

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

Although schema coverage is 100%, the description adds meaning well beyond the schema: it explains the 'value' parameter must be the entity name only, warns that trailing security-class words like 'revenue bonds' will fail FIGI matching, and gives concrete examples for both company and drug types. This materially improves an agent's ability to construct correct calls.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes concrete query examples, names the supported entity types, and explicitly positions itself as the first step when an ID is needed, distinguishing it from sibling tools like entity_profile and search_within.

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 context: 'Use FIRST whenever you have a name but need an ID.' It also clarifies scope by saying it 'replaces 2-3 manual lookups' and describes what inputs are accepted. It does not explicitly exclude alternatives like entity_profile or compare_entities, but the 'Use FIRST' directive provides clear routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by explaining the tool probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density. 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?

Three sentences, each earning its place: purpose, method, use case + output. No unnecessary words, front-loaded with the core action.

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

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

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density). All 4 parameters are covered, and the tool's purpose is fully explained. No gaps for the complexity level.

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 each parameter has a description. The description adds extra context: entities must be 2-8 with first as subject, models explanation, and optional context for disambiguation. This exceeds baseline 3 by providing ordering and limits, improving the agent's understanding.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishes from sibling ai_visibility_check which probes a single entity, and gives a concrete use case (competitive AI-marketing audit). Verb 'compare' plus specific resource 'AI visibility across multiple entities'.

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

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

Description explicitly frames the tool for competitive audits and provides a concrete example ('does Claude know about us as well as our competitors?'). While it doesn't explicitly state when not to use it or name alternatives, the context of sibling ai_visibility_check implies single-entity usage, but this is not explicit in the description. Score 4 because it gives clear context but lacks explicit exclusions.

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 extra behavioral context: fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement may take 5-30s. This adds significant 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?

The description is a single, well-organized paragraph. It front-loads purpose, then usage, then behavioral notes. 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?

Even without an output schema, the description details the return structure (summary fields, advisories, links, alternatives). It covers failure modes and ecosystem scope, making it complete for a composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: scoped packages are accepted and version defaults to latest. This enhances 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 performs a composite check for npm packages using deps.dev and bundlephobia, specifying the verb 'scan' and resource 'dependency'. It distinguishes from siblings by noting other ecosystems are handled elsewhere.

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 an agent asks about safety, popularity, size, or cost of adding a package. Also states ecosystem limitation (NPM only) and directs other ecosystems to deps.dev:version, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds critical behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradictions.

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

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

Four sentences front-load purpose, then add usage guidance, technical details, and constraints. Every sentence adds value; no redundancy or verbosity. 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?

Despite no output schema, description clarifies return format (passages with character offsets and similarity scores). Covers constraints, embedding model, and pairing guidance. Lacks explicit output structure (e.g., array of objects), but adequate for agent to infer.

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

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

Schema descriptions already cover all 3 parameters (100% coverage). Description adds value by reinforcing the 'max ~200K chars' limit for text and providing query examples like 'supply-chain risk' and 'drug interactions with warfarin', helping the agent understand expected input format.

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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). Distinguishes from sibling tools like ask_pipeworx_grounded by explaining pairing. Verb+resource+scope are specific and unambiguous.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests a pipeline pattern: fetch with gateway, then ground over relevant passages. No ambiguity about when to use versus 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?

Discloses OAuth requirement, return of id, rate limits (SMS 10/day), webhook auto-disable after 10 failures, and delivery details. 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?

Compact but dense with information. Could be slightly more structured but every sentence is informative.

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 types, parameters, delivery channels, return value, and constraints. No missing critical info despite 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?

Adds substantial detail beyond schema: explains type-specific params (e.g., items for sec_8k), delivery constraints (phone verification, signing secret). Schema coverage is 100% but description adds value.

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

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

Clearly states the verb 'Create' and resource 'proactive monitoring subscription to a live-data event stream'. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Describes prerequisites (OAuth account), supported types with examples, and delivery channels. Lacks explicit when-not-to-use but provides clear context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about return structure (category-bucketed examples with exact tool shapes) and that it's drawn from live catalog.

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 front-loaded with purpose and example queries. Each sentence adds value, though slightly verbose in listing categories.

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 1-param read-only tool, description fully covers use case, output, and optional parameter. No missing information.

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

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

Schema coverage 100% with description for topic. Description adds meaning by listing example values (finance, pharma, etc.) and stating omit for full spread.

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

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

Description states specific purpose as onboarding entry point returning category-bucketed example questions with tool+argument shapes. Distinguishes from siblings like ask_pipeworx by positioning as first-use tool.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains optional topic parameter for focus.

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 (destructiveHint=false, idempotentHint=true), it reveals that rows are deactivated, not deleted, and ownership is enforced. This adds critical behavioral context.

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

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

The description is just two sentences, front-loading the purpose and then adding key behavioral 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?

For a simple tool with one parameter, good annotations, and no output schema, the description covers purpose, ownership, and side effects, linking to 'recent_alerts' for completeness.

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

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

Schema description coverage is 100%. The description repeats 'by id' from the schema but adds no new semantic details beyond what the schema already provides for the single parameter.

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

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

The description starts with 'Cancel a subscription by id,' using a specific verb and resource. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It states ownership enforcement, implying users should only cancel their own subscriptions. It also explains the deactivation behavior and references 'recent_alerts' for historical events, providing context for when not to use this 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals the dual-pipeline mechanism, the complete verdict vocabulary, and the critical caveat that 'could_not_verify' means the check failed and is not evidence, while 'unsupported' means no source exists. It also discloses the citation format and tolerance override behavior, adding substantial context.

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

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

The description is front-loaded with user phrasing examples and is logically structured. It is longer than a typical description, but the complexity of the tool (two paths, six verdicts, error semantics) justifies the length; every section contributes necessary information without redundancy.

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

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

With no output schema, the description thoroughly covers return values: the six verdicts, the actual value with pipeworx:// citation, reasoning, and the distinction between 'could_not_verify' and 'unsupported'. The two processing paths are explained, and integration with the agent's workflow is clear, making the description complete for its complexity.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds some context about tolerance being implied by wording and capped at 5%, and mentions exact percent-delta math, but it does not add significant parameter-level meaning beyond what the schema already provides for both 'claim' and 'tolerance_pct'.

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

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

The description clearly identifies the tool as natural-language claim verification, enumerates trigger phrases, and specifies two processing paths (company financials via SEC EDGAR/XBRL, all others via grounded pipeline). It also distinguishes itself from multi-step alternatives by stating it replaces 4–6 sequential calls, making its purpose unambiguous.

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

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

The description explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also differentiates sub-cases (company-financial vs other claims) but does not explicitly name alternative sibling tools, which prevents a 5.

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