exchangerate

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

Annotations already mark the tool as read-only, open-world, and idempotent; the description adds meaningful context by disclosing that probing Anthropic requires a BYO key with direct billing to the user, and that the default is free. This goes beyond the schema to explain cost and third-party 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?

Three sentences that each add distinct information: purpose+score, model options/cost, and return shape/use cases. No redundancy or filler.

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

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

With no output schema, the description compensates by detailing the per-model response structure ({score, confidence, signals, raw_response} + combined view). It also covers model selection, cost, and typical applications, making it a self-contained guide for a moderately complex tool.

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

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

Schema covers all four parameters at 100%, so baseline is 3. The description adds value by clarifying the default model ('Workers AI Llama-3.3-70b (free)') and the conditional requirement for _apiKey, surpassing what the schema alone provides.

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

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

The description opens with a specific action ('Probe one or more LLMs for what they know') and defines a measurable outcome (score 0-100). It clearly identifies the resource (business/brand/product/topic) and scope. However, it doesn't explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, relying on 'competitive monitoring' to hint at overlap.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring' which help the agent know when to invoke. No explicit exclusions or comparison to alternatives like scan_competitor_ai_presence, but the context is sufficient.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context about routing behavior, automatic argument filling, stable citation URIs, and performance ('one fast call', 'works on every tier'), which goes 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 lengthy but well-structured and front-loaded with the 'PREFER OVER WEB SEARCH' directive. It uses examples and clear alternates, and each sentence contributes to the guidance, though it could be tightened slightly.

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

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

For a complex tool with no output schema, the description covers purpose, scope, examples, alternatives, expected return behavior, and limitations. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The schema already documents the 'question' parameter and six aliases at 100% coverage. The description includes examples but adds little parameter-level semantics beyond schema, so the baseline of 3 is appropriate.

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

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

The description explicitly states the tool routes questions to 5,564 tools across 1,462 verified sources, returning structured answers with citations. It distinguishes itself from ask_pipeworx_grounded and deep_research by clearly positioning as the default entry point.

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

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

It provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for specific factual data types, and 'START HERE' as default, naming alternatives (ask_pipeworx_grounded, deep_research) and their use cases. It even covers breaking-news edge cases and includes concrete examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds valuable context beyond that: it reveals the beta nature, the possibility of active routing candidates (currently none), and that outputs are compared against the stable router. This behavioral insight is not present in annotations and helps the agent understand the experimental edge 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 well-structured, front-loading the core identity ('Beta version of ask_pipeworx') and then succinctly explaining the experimental state, current behavior, and usage. Each sentence contributes unique information—no fluff or repetition. It is concise while covering critical distinctions and clarifications.

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 router tool with a single required question parameter and no output schema, the description is remarkably complete. It explains the tool's relationship to ask_pipeworx, the current no-candidate state, the fallback behavior, and the comparison purpose. Annotations cover safety, and the description fills all contextual gaps, making it sufficient for an agent to decide when and how to use 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 description coverage is 100%, so all parameters (including aliases) are well documented in the schema. The description adds only a generic statement 'same arguments' referencing ask_pipeworx, which does not provide additional parameter semantics. Per guidelines, baseline is 3 when schema coverage is high, and the description does not compensate with extra meaning.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router, and explicitly distinguishes it from siblings by mentioning 'identical universal router' and pointing to ask_pipeworx as the stable alternative. It conveys the exact scope (same tools, arguments, response shape) and experimental nature, making the 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 provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It further explains results are compared against the stable router to decide merges, implying use for testing/experimental scenarios. It also clarifies it is a full working router, avoiding any misconception that it might be a stub.

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

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

Annotations already mark readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: refusal reasons (not_in_source, no_tool_match, etc.), the evidence quoting mechanism, and the cost trade-off. No contradiction with annotations; significant added value.

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

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

The description is long but every sentence earns its place: purpose, routing, extraction, output format, usage examples, cost warning. It's efficiently structured with front-loaded purpose and critical usage details. Minor redundancy like 'Same routing as ask_pipeworx' echoes sibling tool name but adds clarity.

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 fully explains return structure (success object with evidence/confidence/source and refusal object with reasons). It addresses edge cases (data truncated, no tool match) and ties back to usage context. Complete for a complex grounded-answer 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% (all parameters are aliases for 'question'), and the description repeats that 'question' is natural language with aliases. Since the schema already documents the parameter, the description adds no new semantic information. Baseline 3 appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that routes through 5,564 tools, fetches data, and extracts answers only from tool results. It explicitly distinguishes from 'ask_pipeworx' by adding evidence extraction and refusal logic, making the purpose specific and sibling-differentiating.

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

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

The description provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also warns of the extra LLM cost and advises preferring 'ask_pipeworx' for casual lookups. This is a model example of when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral traits: the resolver contract with match confidence and alternatives, safety mechanisms (low_confidence_match, market_closed_or_inactive), news fallback fields, wide-spread illiquidity warnings, and resolution-rule risk with void settlements. This transparency goes far beyond what annotations provide.

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

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

The description is exceptionally long and detailed, with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, etc.) that improve structure. However, the sheer volume of text, including multiple fan-out examples and edge cases, makes it less concise than ideal for a tool description. It is organized but could be trimmed without losing critical information.

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

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

Despite lacking an output schema, the description fully documents response shapes (result.market, result.analysis, result.evidence), error/blocking states, resolver behavior, and rule risks. It addresses complex edge cases thoroughly, making it contextually complete for a tool with this level of 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?

The input schema already covers all three parameters with detailed descriptions and examples (100% coverage), so the baseline is 3. The description adds context on how the 'market' parameter is resolved and mentions depth/raw behavior, but it does not introduce new parameter-level semantics beyond the schema.

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

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

The description opens with a specific verb ('Research') and resource ('Polymarket bet'), then details input formats (slug, URL, question text) and the workflow (resolve, classify, fan out, return evidence). This clearly distinguishes it from sibling tools like polymarket_arbitrage or deep_research, which focus on different aspects.

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

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

The description provides an explicit 'Use for' list that covers common trigger scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), and gives detailed fan-out examples per category. However, it does not name alternative tools or explicitly state when not to use this tool, stopping short of a 5.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and that it returns paired data plus citation URIs. This goes far beyond the annotations, providing rich behavioral 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 compact yet information-dense, starting with trigger phrases, then core behavior, then type-specific details and output. Every sentence adds value: scope, metrics, data sources, sorting, citations, and comparative benefit. No fluff or repetition, ideal for AI consumption.

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 explains return values ('paired data + pipeworx:// citation URIs per entity'), covers both types' behavior, data sources, sorting logic, and even highlights edge-case handling (off-calendar fiscal years). It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, but description adds significant meaning: type='company' explains what metrics are pulled (latest 10-K revenue, net income, cash, long-term debt), while type='drug' explains FAERS and FDA counts. Values format is clarified with examples and constraints (tickers/CIKs vs names, 2–5 items). This substantially enriches parameter understanding.

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

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

The description uses a specific verb ('compare') plus resource ('2–5 companies or drugs') and clearly differentiates from siblings by declaring 'ALWAYS PREFER over sequential single-pack lookups' and stating it does side-by-side comparison in one parallel call. It also lists concrete metrics per type, making the purpose unmistakable.

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

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

Explicit trigger phrases are provided ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies'), and the description explicitly says to prefer this tool over sequential single-pack lookups. It distinguishes when to use company vs drug type and notes it replaces 8–15 sequential lookups, giving 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 declare read-only/idempotent, but the description adds substantial context: expected latency (15-90s), gap recovery behavior, semantic excerpting, citation URI fetchability, contradictions array, and the guarantee of never inventing evidence. This far exceeds what annotations convey.

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

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

The description is a dense single paragraph packing in pricing, auth, timing, edge cases, and return semantics. It is information-dense but hard to scan; bullet points or section headers would greatly improve readability. Still front-loaded and no wasted words, but structure lags.

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 two-parameter tool with no output schema, the description covers inputs, depth semantics, return findings packet, gaps, contradictions, citation format, performance expectations, and account requirements. It effectively compresses an entire API reference into a coherent narrative, leaving no critical gap.

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

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

Although schema coverage is 100%, the description enriches both params: it details the 'depth' enum's facet counts, hop behavior, and contradictions scan, and clarifies that 'question' can be broad or multi-part. This adds meaningful decision-making value beyond the raw 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 performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to parallel tools. Explicitly distinguishes itself from siblings like ask_pipeworx, making its unique purpose unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance, including alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers account/tier prerequisites and expected use cases, leaving no ambiguity about tool 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 declare the tool as read-only, idempotent, and non-destructive. The description adds important behavioral detail beyond annotations: it returns top-N results with names, descriptions, and full input schemas (with curated examples), ready to call directly without a second schema lookup. 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 somewhat long due to the enumerated domain list, but the list is informative and each sentence serves a purpose: definition, use case, output format, and 'call first' guidance. The structure is front-loaded with a clear opening sentence and remains focused.

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 present, the description adequately explains what the tool returns (top-N tools with names, descriptions, and full input schemas) and the convenience of direct invocation. It also provides overall context for when to use this tool in the broader toolkit, making it sufficiently complete.

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

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

Schema coverage is 100%, with descriptions for the query parameter, its aliases, and the limit parameter, so the schema already documents parameter semantics well. The description reinforces natural-language query usage with examples but does not add significant new parameter information beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Find tools') and clearly identifies the tool as a discovery meta-tool for browsing, searching, or looking up available tools. It enumerates many supported data domains and distinguishes itself from sibling tools by focusing on tool discovery rather than direct data access.

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

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

It explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to 'Call this FIRST' when many tools are available. It does not name specific alternatives, but the context and the qualifier 'not just one answer' provide clear usage direction.

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, and the description adds rich behavioral context beyond that: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields with a defined output structure; discloses USPTO PatentsView API sunset with soft-fail behavior; and explains GDELT→GNews fallback. 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 information-dense but verbose: seven nearly identical example queries ('Tell me about X', 'research Acme', 'brief me on Tesla', etc.) could be condensed to one or two. However, the later sections are well-structured with semicolon-separated return field lists and clear fallback notes, so it is not overly rambling.

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

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

There is no output schema, so the description must carry the full burden of explaining return values. It does this thoroughly: lists exact fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI), notes data source limitations and fallbacks, and even flags a known API sunset. For a multi-source tool, 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 description coverage is 100% and both parameters are already well-documented in the input schema (type enum 'company' and ticker/zero-padded CIK). The description repeats the same parameter semantics without adding new detail beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with many concrete examples ('Tell me about X', 'research Acme') and immediately defines the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups,' making the tool's distinct role unambiguous.

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

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

The description provides explicit usage context ('when the user asks for a holistic view'), explicitly warns against chaining single-pack lookups, and names the alternative for unsupported input: 'names not supported (use resolve_entity first if you only have a name).' This is a clear when-to-use and when-not-to-use with a specific sibling tool.

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

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

The description's 'Delete' aligns with the annotations' destructiveHint=true and idempotentHint=true. It goes slightly beyond annotations by mentioning clearing sensitive data and pairing with related tools, but it does not add details about irreversibility, failure modes, or permissions. Since annotations already cover the core safety profile, a score of 3 is appropriate.

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

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

The description is two sentences with no redundant words. The first sentence states the action and target; the second provides when-to-use and related tools. Every sentence adds value, making it appropriately sized.

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 one-parameter destructive tool with rich annotations, the description covers purpose, usage, and related tools. It does not mention what happens after deletion (e.g., success message or error for missing key), but given the tool's simplicity and the lack of an output schema, this is a minor gap. Overall it is well-rounded.

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

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

Schema description coverage is 100% for the single 'key' parameter, so the baseline is 3. The description only says 'by key', which adds no new meaning beyond the schema's 'Memory key to delete'. No extra syntax, formatting, or examples are provided 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 uses the specific verb 'Delete' with the resource 'a previously stored memory' and specifies the mechanism 'by key'. This clearly distinguishes it from sibling tools like recall and remember, which retrieve or store memories.

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

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

It provides explicit use cases ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember and recall. It lacks an explicit 'do not use when' statement, but the guidance is clear enough for most scenarios.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds context about the internal process (fetch page, extract, emit markdown) and the output format (single text blob for site-root), which goes beyond annotations without contradicting them.

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

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

The description is concise and front-loaded, with the main purpose in the first sentence and supporting details and use cases that follow. Every sentence earns its place without unnecessary elaboration.

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 simple parameters and no output schema, the description compensates by explaining the output format (text blob) and intended deployment location. It omits potential error scenarios, but given the low complexity and supportive annotations, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with both url and max_links fully described in the schema. The description indirectly mentions 'key links' in relation to max_links but does not add new syntax or format details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'generates a production-ready llms.txt file for any URL,' with a specific verb and resource. It also outlines the process (fetch, extract title/description/key links, emit standard markdown) and distinguishes from siblings by focusing on the output artifact, llms.txt, rather than visibility checking or scanning presence.

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 'Useful for' scenarios, including indexing a client's site, drafting llms.txt, and auditing a competitor. This gives clear context for when to use the tool, though it does not mention alternatives or exclusions explicitly.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it returns the conversion rate and that the rate is 'current', providing a bit of behavioral context. However, it does not elaborate on data source, rate freshness guarantees, or other limitations, so it adds limited value beyond the annotations.

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

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

The description is two sentences with no filler. It front-loads the core action ('Get the current exchange rate'), provides an example, and a usage note. Every sentence adds value and the structure is ideal for quick parsing.

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

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

Given the tool's simplicity, two clearly documented parameters, an output schema, and robust annotations, the description is nearly complete. It states the purpose and usage context. It does not explicitly mention how to handle multiple currency pairs (e.g., pointing to get_rates), which is a minor gap but not critical given the phrase 'single currency pair lookups'.

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 provides 100% coverage with descriptions for both 'from' and 'to' parameters. The description's example ('USD to EUR') and phrase 'specific currencies' adds no new semantics beyond what the schema already documents. The baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: getting the current exchange rate between two specific currencies, with an explicit example (USD to EUR). It also distinguishes itself from siblings by specifying 'single currency pair lookups', which contrasts with the likely multi-pair sibling get_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?

The description gives clear context: 'Use for single currency pair lookups.' This implies when to use it (single pair) and indirectly that multi-pair requests should use another tool (like get_rates). It does not explicitly name alternatives, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds that rates are 'current' and returns 'all major currencies,' but does not disclose rate source, validity, or error behavior. This is acceptable given annotations but not rich.

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

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

The description is two sentences, front-loaded with purpose, then return scope and a usage hint. No wasted words, each sentence earns its place.

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

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

For a simple one-parameter tool with a rich annotation set and an output schema, the description is complete enough. It covers what it does, what it returns, and when to use it. Minor vagueness about 'all major currencies' is acceptable.

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 base_currency fully described as an ISO 4217 code with examples. The description repeats examples ('USD', 'EUR') but adds no additional meaning or context beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets current exchange rates for a base currency, which is specific and distinguishes it from the sibling 'get_pair' by noting it returns all major currencies at once. The verb 'Get' and resource 'exchange rates' are explicit.

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

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

The description provides a clear usage context: 'Use when you need multiple rates at once.' This implies a single pair tool (like get_pair) would be more appropriate for one rate, though it does not explicitly name alternatives or 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=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds useful context beyond annotations by specifying the returned fields and noting that it lists active subscriptions by default, which is valuable for an agent deciding whether to use this tool.

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

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

The description is two sentences with no redundancy. The first sentence states the purpose and return fields; the second gives usage guidance. Information is front-loaded and every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description is complete. It names the returned fields, provides usage context, and the annotations cover safety. No output schema exists, but the description compensates by listing return fields. Given the tool's simplicity, no further details are necessary.

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 the include_inactive parameter clearly described ('Include cancelled subscriptions in the response (default false)'). The description does not add further parameter-specific details, and the baseline 3 is appropriate when the schema already handles parameter semantics well.

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

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

The description states a specific verb and resource: 'List the caller's active subscriptions.' It also lists the return fields, making the scope clear. It distinguishes from sibling tools like subscribe and unsubscribe by framing its use as 'review what you're monitoring before adding more or to find an id to cancel.'

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

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

The description provides clear use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use the tool (before subscribe/unsubscribe) and references the alternatives indirectly. It does not name sibling tools explicitly but gives sufficient 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?

Beyond the all-false annotations, the description discloses rate limiting (5 per identifier per day), no quota impact, the claim_token follow-up mechanism, and that the team reads digests daily. This adds substantial behavioral context without contradicting annotations.

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

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

Though long, every sentence delivers useful information. It front-loads the core purpose, then efficiently covers usage, exclusions, follow-up, rate limits, and cost — no filler.

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

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

With no output schema, the description explains the return behavior (claim_token), how to use it to read status, and the tool's scope. It fully equips an agent to decide when and how to invoke the tool without needing additional documentation.

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

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

Schema coverage is 100%, and the description enriches parameters by giving a concrete example of claim_token usage ('pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying message expectations. This goes well beyond the schema.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team) and differentiates itself from siblings like ask_pipeworx by focusing on feedback rather than queries.

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

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

It explicitly enumerates when to use the tool (bug, feature, data_gap, praise) and provides a strong exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This gives agents clear decision boundaries.

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

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

The description goes beyond the readOnlyHint by explaining the aggregation source (CF analytics-engine), explicit no-PII guarantee, the output shape (pack, tool, count), and cache duration (5min–1h). 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 compact yet rich: the first sentence defines the output, the second lists concrete use cases, and the third covers data provenance and caching. No redundant phrasing.

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 read-only aggregate tool with a single optional parameter, the description covers output content, temporal windowing, caching, and privacy. The output schema is absent, but the description specifies the return elements (pack, tool, count), making it 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?

The schema already fully documents the 'window' parameter with enum and semantics. The description reinforces the distinction between short and long windows and adds that cache varies by window, providing extra context 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 returns trending AI agent calls (top tools, top packs, call volume) over a 24h/7d/30d window. It differentiates from siblings like discover_tools by focusing on aggregate usage signal rather than tool lookup.

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 'Useful for' section explicitly lists three scenarios that guide an agent on when to call this tool, covering hot data discovery, canonical tool confirmation, and use-case alignment. It doesn't name specific alternatives or exclusions, but the context 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?

The description discloses rich behavioral details beyond the annotations: the 3pp threshold for signals, the ≥0.30 Jaccard similarity anchor, placeholder filtering, and the fill-check pricing against live CLOB depth with realizable_edge_pp ≤ 0 as a do-not-trade signal. These are non-obvious behaviors that augment the readOnly/idempotent hints.

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

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

The description is long but front-loaded with purpose and then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize dense information. Every sentence contributes actionable behavior, and the length is justified by the tool's multi-mode 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?

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: opportunities[] fields, partition_check structure, and fill_check outputs including thin_legs[]. It also covers failure/edge cases like skipped_low_similarity and placeholder fractions, making the tool self-contained.

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

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

While schema already covers both parameters at 100%, the description adds usable examples ('fed-decision-may-2026'), states that full Polymarket URLs are accepted, and explains what happens with each parameter (walks child markets; searches related events). This materially enriches the bare schema definitions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk by naming the detection methods.

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

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

It explicitly defines three usage modes: no args for trending_scan, 'event' for single-market checks, and 'topic' for cross-event scans. It also recommends which to use ('event (recommended for a specific market)') and points to a sibling 'For custom sizing use polymarket_fill_risk.'

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

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

Despite strong annotations (readOnly, idempotent, openWorld), the description adds substantial behavior beyond them: it details response structure, cached 1h at KV level, edge_pp_net after slippage, kelly caps, 24h-move warnings, diagnostics explaining empty segments, and specific caveats like the Fed note that '1m-T vs EFFR signal is unreliable.' It also discloses that partition arbs always return kelly_fraction_half=0 at parent level. This is rich, non-obvious context that helps the agent interpret results.

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 it is well-structured with clear section labels (TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loaded purpose. Every sentence carries specific strategic or operational detail, though some historical notes like 'gates relaxed Run 8 from prior 85%/5%/50:1' may be overly granular for typical agent invocation. Overall it earns its length.

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

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

There is no output schema, so the description must fully document the response shape. It does: it explains top-level by_segment, fed_candidates/fed_note, and _diagnostics, and details per-opportunity fields (edge_pp_net, kelly_fraction, kelly_fraction_half, market.liquidity, spread_pp, volume, plus 24h-move warnings). It also explains why segments may be empty, making the tool self-contained for the agent.

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

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

Schema coverage is 100% with parameter descriptions, so the baseline is 3. The tool description goes further by explaining why knobs exist and how they interact: for example, min_liquidity and max_spread_pp 'drop opportunities where edge isn't realizable'; min_partition_leg_kelly is clarified because 'partition arbs always return kelly_fraction_half=0 at the parent level by design,' so min_kelly never filters them. It also justifies slippage_pp defaults with market microstructure rationale (Polymarket zero fees but 20-50bp bid/ask costs). This adds meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's goal ('what should I bet on today') and differentiates itself from simpler market lookup tools by describing a multi-model opportunity scan with distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which separates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly frames the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear context for when to use the tool. However, it does not explicitly state exclusions or point to alternatives for specific scenarios, so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond annotations: 60-day snapshot TTL, gaps meaning no scan, decay computed from daily closes, and the difference between signed edge values. This goes well beyond the readOnly/idempotent hints and provides valuable 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 long but exceptionally well-organized with clear sections (ARGS, RESPONSE, LIMITS). Every sentence adds critical detail, and the purpose is front-loaded. The structure makes the length acceptable and the content highly 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?

The description thoroughly explains the response structure (tracked, expired, snapshot_dates), the meaning of derived metrics, and the limitations of the data. With no output schema, this detail is essential and does not rely on external documentation.

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

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

Schema coverage is 100% and the schema already describes both parameters with defaults and allowed values. The description mostly restates parameter semantics (e.g., days lookback, window family) with minor additions like 'snapshot family' and 'max 30', but does not significantly enrich 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge age and decay, and the focus on persistence distinguishes it from sibling tools like polymarket_edges, which likely provides 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 this tool: 'a fresh wide edge and a 3-week-old wide edge are different trades' – suggesting it is for assessing edge longevity. However, it does not explicitly name alternative tools or provide when-not-to-use guidance. Clear context, but no 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=true, idempotentHint=true, destructiveHint=false, but the description goes far beyond: it details the walking of the order-book ladder, enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and explains the risk model (forced_directional_risk). This adds substantial behavioral context without contradicting annotations.

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

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

The description is long but information-dense and well-structured: it opens with a one-sentence purpose, then uses SCREAMING CAPS for key requirements and mode demarcations. It lists return fields in each mode and ends with a usage directive. Every sentence earns its place; no redundancy or waffle.

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: it enumerates the return fields for both single-market and basket modes, including verdicts, per-leg details, thin_legs, and max_clean_notional_usd. It also explains the risk of partial fills, making the tool's behavior fully predictable.

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

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

While the schema has 100% parameter coverage with basic descriptions, the tool description enriches every parameter: it clarifies the mutual exclusivity of market/event, provides mode-specific side semantics (buy_yes/sell_yes default auto in basket), and explains size_usd interpretation (spend vs proceeds vs settlement notional). This goes well beyond the schema.

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

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

The description opens with a specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly names the tool's function, scopes it to single-market and basket modes, and contrasts with sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges usage contexts. This uniquely identifies the tool's role.

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

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

The description specifies exactly when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills convert arb to unhedged directional position), providing clear context and rationale 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?

With annotations already declaring readOnlyHint and destructiveHint:false, the description goes far beyond by explaining compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It openly states that most pre-mapped topics currently return warnings, providing honest expectations about real-world 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 densely packed with essential information. It front-loads the core concept, then systematically covers modes, response structure, and safety fields. Every sentence contributes meaningful context, though the length approaches the upper limit of conciseness.

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

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

There is no output schema, so the description fully takes on the burden of explaining return values: leg-by-leg prices, matched spreads, and safety fields. It also covers edge cases (compatibility warnings, temporal misalignment) and explains why spreads may be meaningless, making the tool's behavior fully transparent.

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 covers all three parameters (topic, kalshi_event_ticker, polymarket_event_slug) with descriptions. The tool description adds value by explaining how the parameters interact: explicit tickers override topic-mapped sides, and it details the two modes. This goes beyond the schema's basic property descriptions.

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

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

The description clearly states the tool's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by specifying the cross-venue nature and the concept of matching bet shapes.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug) and provides guidance on when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings, making them not tradeable, which sets expectations for when not to rely on the tool. However, it does not explicitly name sibling alternatives 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 readOnly, idempotent, non-destructive. The description adds useful behavioral context: the omission of key triggers listing, and data is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID). This adds value beyond the annotations without contradiction.

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

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

The description is three sentences, front-loaded with the primary action, then usage context, scoping, and pairing. Every sentence contributes meaningful information with no redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the operation, the list mode, scoping, and related tools. It does not specify the exact return format or behavior on missing keys, but these are minor gaps given the tool's simplicity.

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 explains the key parameter ('Memory key to retrieve (omit to list all keys)'). The description repeats this same info with examples (ticker, address, notes) but does not add new parameter syntax or format details beyond what the schema provides.

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

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

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), plus a secondary mode ('list all saved keys'). It clearly distinguishes from sibling tools remember (save) and forget (delete).

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 when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions the companion tools remember and forget, but does not explicitly state when not to use this tool vs alternatives.

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

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

The description goes beyond the annotations by disclosing the side effect of mark_read:true ('flag returned events read so the next call only shows newer ones') and describing the return payload (source, citation_uri, raw event). It also notes that polling is fine, addressing potential reliability concerns. This is exactly the kind of behavior context that annotations don't provide.

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

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

The description is three tight sentences: the first states purpose and return contents, the second covers filtering and mark_read, and the third addresses polling alternatives. Every sentence earns its place, with no fluff or redundancy. The structure is front-loaded with the core action, making it easy for an agent to parse.

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

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

For a read-only tool with 5 optional parameters and no output schema, the description covers all critical aspects: what the tool returns, how to filter, the mark_read side effect, and polling behavior. It even provides an alternative access method. The inclusion of return payload details compensates for the lack of an output schema, making the description sufficiently complete for an agent to invoke the tool correctly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the behavioral effect of mark_read. These enrich the raw schema definitions without repeating them, justifying a score above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb+resource statement that clearly identifies the tool's function. It distinguishes itself from subscription management siblings like list_subscriptions and subscribe by focusing on the feed of fired alerts, and mentions the returned data fields (source, citation_uri, raw payload), leaving no ambiguity about its scope.

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

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

The description provides clear usage context: it states that polling works fine and offers an explicit alternative (the HTTP endpoint at registry.pipeworx.io/alerts.json) for scripts and dashboards. While it doesn't contrast with specific sibling tools, it does guide an agent on when to use this tool versus a non-tool alternative, which meets the bar for 'clear context, no 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?

Beyond the annotations, the description reveals internal fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), the soft-fail of USPTO due to API sunset, and the output structure (changes[] grouped by source, total_changes, citation URIs). This gives the agent a realistic model of the tool's behavior and limitations.

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

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

The description is longer than simple tools but every sentence is purposeful: the opening examples clarify intent, the fan-out explanation is dense but readable, and the alternative-tool guidance is valuable. It is front-loaded with natural language examples and structured logically.

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 multiple data sources and fallback logic, this description is remarkably complete. It covers the core behavior, output shape, source limitations, and even suggests parameter values. The annotations provide safety context, and the description fills in the behavioral details, so an agent can invoke the tool correctly without additional information.

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

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

The input schema already provides comprehensive descriptions for all three parameters (100% coverage), including examples for `since` and formats for `value`. The description reiterates the `since` examples but does not add new semantic meaning beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly defines a 'change feed for a company' with concrete examples of user intents, and lists the exact data sources (SEC EDGAR, GDELT/GNews, USPTO). It also explicitly distinguishes itself from entity_profile, a sibling tool, by contrasting dynamic changes vs. 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 usage guidance: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also recommends a specific value for `since` ('30d' or '1m' for typical monitoring), which helps the agent choose parameters appropriately.

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 annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and it notes relationships with recall/forget. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Three sentences, each earning its place: purpose in the first, usage examples in the second, storage/persistence details and sibling relationships in the third. Front-loaded with the core verb and resource.

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

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

For a simple write operation with full schema coverage, annotations, and clear usage guidance, the description is complete. It explains the full lifecycle (save, retrieve, delete) without needing an output schema.

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

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

Schema documentation covers 100% of parameters (key, value) with clear descriptions and examples. The description's mention of key-value pair adds no new semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' — a specific verb and resource (key-value memory). It distinguishes itself from sibling tools by explicitly pairing with recall and forget, making its role in the memory toolset 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?

Explicit guidance on when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It also directs to alternatives: 'Pair with recall to retrieve later, forget to delete', which prevents misuse.

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 as false. The description adds significant behavioral context: it cascades through multiple lookup endpoints, degrades gracefully (if GLEIF/OpenFIGI unavailable, EDGAR still returns), and explicitly returns unresolved identifiers. This goes well beyond what annotations provide.

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

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

The description is front-loaded with examples and structured clearly, but it is relatively long. Every sentence adds value, though some details (e.g., ISIN explanation) could be slightly condensed. Overall, it is well-organized and 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?

Given the tool has no output schema, the description thoroughly explains return values: identifiers from various sources, explicit 'unresolved' labels, and graceful degradation. It covers error handling and edge cases (ISIN resolution, non-US issuers). The description is complete for a resolution tool of this complexity.

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

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

Schema description coverage is 100% with both parameters described. The description adds substantial meaning: for 'type' it lists supported values and explains what each returns (e.g., company returns CIK, ticker, LEI, FIGI), and for 'value' it provides examples and input formats (ticker, CIK, ISIN, company name). This significantly enhances the schema's minimal 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 uses specific examples of user queries ('What's the ticker for…') and clearly states the verb (resolve) and resource (entity names to canonical identifiers). It distinguishes itself from siblings by specifying 'Use FIRST whenever you have a name but need an ID' and mentions it replaces 2-3 manual lookups, making its purpose distinct among sibling tools.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also outlines supported types and what each returns, implying when to use this tool. However, it does not explicitly state when not to use it or offer alternatives, leaving some room for ambiguity.

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, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context: it performs multiple probes internally, ranks results by score, and returns a ranked list with score, confidence, and signal density per entity. This goes beyond the annotations, though it does not discuss rate limits or potential failures when external models are used.

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 pack in the main purpose, method, an example use case, and the return structure. Every sentence earns its place, and the description is front-loaded with the core action. 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?

Given the tool's aggregation complexity and lack of output schema, the description covers the key points: what it does, how it works (internal probes), what it returns (ranked list with score/confidence/signal density), and typical use. It does not mention entity count limits (schema covers that) or error handling, but the essentials are present. Slightly more detail on output schema or potential model failures would push it to 5.

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 parameters are already documented. The description adds value by describing the first entity as the 'subject' for narrative and others as competitors, plus the purpose of context for disambiguation. This enriches the schema without repeating it, making parameter usage clearer.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility), the action (compare), and distinguishes from siblings by explicitly mentioning it probes each entity with ai_visibility_check and ranks them, positioning it as a multi-entity aggregator.

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 for when to use the tool ('competitive AI-marketing audits') and includes a concrete example question. It implies the alternative (single-entity check via ai_visibility_check) by stating it probes each entity with that tool, but does not explicitly say 'use this instead of ai_visibility_check when you need side-by-side comparison.' Minor gap for an explicit when-not.

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 failure behavior and performance characteristics beyond annotations: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This complements annotations (readOnlyHint, idempotentHint) and adds operational context. No contradiction with annotations is present.

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

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

The description is dense but every sentence contributes: purpose, usage, ecosystem scope, failure handling, and return details. It is front-loaded with the primary purpose, and the follow-up details are logically ordered. No fluff or redundant 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 having no output schema, the description enumerates the returned summary block fields, per-advisory details, links, and alternative versions. It also explains timeout behavior. This gives a complete mental model of the tool's behavior and outputs, fitting for a composite tool with multiple data sources.

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

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

The input schema already provides 100% coverage for both parameters ('package' and 'version') with clear descriptions. The tool description adds minimal additional parameter semantics, mainly reinforcing that package is an npm package name and version defaults to latest. Since schema coverage is complete, a baseline score of 3 is appropriate.

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

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

The description states a specific composite purpose: 'Composite "should I add this npm package to my project" check in ONE call — fans out across deps.dev and bundlephobia.' It clearly identifies the resource (npm package) and the action (scan/check). It also distinguishes itself from siblings by focusing on npm dependency analysis, while siblings like scan_competitor_ai_presence target different domains.

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

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

Explicit usage is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also excludes non-NPM ecosystems: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and when-not-to-use guidance.

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

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

The annotations already declare readOnly/idempotent, but the description adds algorithmic specifics (BGE-base-en embeddings, cosine, 500-char overlapping windows) and the 200K-char truncation behavior with a flag. It also states that results include offsets for verifying verbatim quotes.

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?

Five meaningful sentences that front-load purpose, then workflow, algorithm, and constraints. No filler; every detail serves a 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 exists, so the description carries the burden of explaining returns; it does so explicitly (passages, offsets, similarity scores). It covers input constraints, algorithm, pairing, and use case, fully equipping an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'text' parameter by giving real-world examples (SEC 10-K, article, long tool result) and clarifies how 'query' should be phrased. It also ties 'limit' to 'top-N passages'.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It details inputs (text, query) and outputs (top-N passages, character offsets, similarity scores), distinguishing itself from siblings by explicitly comparing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also names a complementary sibling (ask_pipeworx_grounded) and explains the workflow: fetch with the gateway, ground over relevant passages.

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:false, idempotentHint:true, destructiveHint:false), the description adds significant behavioral context: the need for an OAuth account, phone verification for SMS, a 10/day SMS cap, and webhook auto-disable after 10 failures. It also clarifies that the feed is always on and that the new subscription ID is returned. These traits are not inferable from annotations alone.

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

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

The description is dense but efficient, packing purpose, prerequisites, type examples, and delivery details into a single well-structured paragraph. Every clause adds value, and the use of em-dashes and parentheticals keeps related information tightly grouped. No filler words or redundancy.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, auth requirements) and the rich schema, the description covers the essential operational details: return value, auth prerequisite, type-specific examples, feed behavior, and delivery verification/caps. The schema fills in the remaining type specifics (patent_grant, clinical_trial) and webhook details, so the description is not required to duplicate everything.

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

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

Although schema coverage is 100%, the description enriches parameter understanding with concrete examples and constraints: e.g., items:["5.02"] means officer change, phone must be verified, and SMS has a daily cap. The schema's params field lists structures but does not explain the semantics as clearly or provide illustrative examples for delivery nuances beyond what the schema gives.

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 begins with a clear verb+resource+context: 'Create a proactive monitoring subscription to a live-data event stream.' It explicitly says it returns the new subscription ID, distinguishing it from siblings like list_subscriptions and unsubscribe. The enumerated supported types further solidify the tool's purpose.

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

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

The description clearly implies when to use this tool (to create a persistent subscription) and provides exclusions: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also mentions delivery channels and how to pull the feed via recent_alerts, offering practical usage context. However, it does not explicitly name sibling tools like list_subscriptions or unsubscribe as alternatives, so it stops short of a 5.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds meaningful context: results are drawn from the 'live catalog of thousands of tools,' the output is grouped by category, and each example includes the resolving tool and argument shape. No contradiction; these details go beyond what annotations provide.

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

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

The description is long but every section serves a purpose: user-phrase examples, return content, invocation modes, and strategic placement. It is front-loaded with natural-language triggers and uses a structured category list rather than prose. Slightly wordy in the opening phrase list, but appropriate for an onboarding tool.

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

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

No output schema exists, so the description carries the return-value burden; it explains the categorical buckets and that each item maps to a concrete tool/argument shape. It covers the zero-parameter call, optional `topic`, and a clear first-use scenario. The live-catalog note sets expectations about freshness, making the description complete for this tool.

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

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

The schema fully describes `topic` with allowed focus areas and omission behavior, so schema coverage is 100%. The description mostly restates this ('pass topic to focus') and only adds an extra example ('betting') already present in the schema. This meets the baseline but doesn't add substantial new semantics.

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

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

The description names the tool as the 'onboarding entry point' and specifies the exact deliverable: category-bucketed example questions paired with the exact tool and argument shape. It clearly distinguishes from sibling discovery tools by its focus on prompting the user with 'what can I ask' rather than raw tool lookup. Specific verb+resource: 'Returns category-bucketed example questions'.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' or to learn how to call the meta-tools, naming ask_pipeworx, entity_profile, compare_entities. This is an explicit when-to-use directive with concrete alternatives. It also explains the no-argument vs `topic` invocation modes.

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 (destructiveHint=false, idempotentHint=true), the description discloses that the row is deactivated rather than deleted and that historical events remain accessible via recent_alerts. This adds meaningful behavioral context about side effects and data persistence.

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, each carrying essential information: the primary action in the first sentence, and key behavioral details in the second. No filler or redundancy.

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

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

For a simple one-parameter tool, the description covers the action, ownership constraint, side effect (deactivation), and data persistence. Combined with clear schema and annotations, it fully equips 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 schema already fully describes the 'id' parameter with type and provenance ('Subscription id (uuid) returned by subscribe'). The description only restates that canceling happens by id, adding no new semantic detail. Baseline 3 is appropriate given 100% schema coverage.

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 action and target: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe and list_subscriptions. The verb 'cancel' and resource 'subscription' are unambiguous.

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

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

The description provides clear context on usage, including ownership restrictions ('you can only cancel your own subscriptions') and the deactivation behavior. It does not explicitly name alternatives or when not to use, but the context is sufficient for a single-purpose 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 indicate readOnly/openWorld/idempotent, but the description adds critical behavioral details: the two processing paths (SEC EDGAR vs grounded), the verdict enum, and the crucial distinction between could_not_verify and unsupported, including the requirement not to present could_not_verify as evidence. This far exceeds the annotation baseline.

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

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

The description is longer than ideal but every section — query patterns, usage, paths, return values, failure-mode warning — earns its place. It is front-loaded with purpose and ends with the critical caller note, maintaining a logical structure 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?

Without an output schema, the description fully explains return values and the meaning of each verdict, especially the tricky could_not_verify case. It also covers the two routing paths and the tolerance behavior, making it self-sufficient for a complex tool.

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

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

Input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description does not add meaning beyond the schema; it mentions 'exact percent-delta math' but that is already implied by the tolerance_pct schema text.

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: 'natural-language claim verification against authoritative sources' with explicit trigger phrases. It distinguishes from siblings by noting it replaces 4–6 sequential calls and handles both financial and non-financial claims.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. However, it does not name alternative tools or provide explicit when-not-to-use conditions, though the grounded pipeline description implies coverage for all factual claims.

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