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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it routes to one of 5,798 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs, which is useful beyond the annotations. It does not mention latency, rate limits, or failure behavior, but nothing here contradicts the annotations.

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

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

The description is longer than typical, but it earns its length by front-loading the key directive ('PREFER OVER WEB SEARCH'), providing a domain list, examples, and sibling-tool routing in one coherent block. There is minor redundancy and a slightly awkward transition near 'START HERE', but no wasted sentences.

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 routing tool with one natural-language input and no output schema, the description is remarkably complete: it covers when to use it, what it does internally, what the output looks like (structured answer with citations), and how it relates to sibling tools. An agent has enough context to invoke it correctly in most situations.

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 six parameters are described as aliases for the single natural-language 'question' parameter, with examples. The description does not add parameter-specific syntax or formatting guidance, but the schema already fully documents the only meaningful input, so the baseline of 3 applies.

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

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

The description clearly identifies a specific verb (routes/answers) and resource (Pipeworx's tool network), and explicitly contrasts it with web search. It enumerates the domains covered (SEC filings, FDA data, FRED/BLS, patents, news, etc.) and the output form (structured answer with pipeworx:// citations), so an agent understands exactly what this tool does and how it differs from a generic search.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH' for factual or data-oriented questions, with concrete example phrasings and sample queries. It also names alternatives — ask_pipeworx_grounded for a single direct answer and deep_research for broad/multi-part queries — and specifies when to use each, making the routing decision clear.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description adds valuable live-behavior context: routing improvements are enabled only when a candidate is under test, no candidate is active as of 2026-07-26, and it falls back to nothing. This is clear and does not contradict annotations.

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

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

Four sentences, front-loaded with beta status, then state, usage, and a clarifying fallback. Every sentence adds distinct information and there is no filler.

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

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

For a beta alias whose schema and annotations are rich, the description is nearly complete: it gives current experimental status, exact parity with ask_pipeworx, and full functional promise. The only minor gap is that the exact response format is delegated to 'same response shape' rather than described in detail.

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

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

All six parameters are documented in the schema with 100% description coverage (question plus five aliases). The description only references 'same arguments' as ask_pipeworx, but no further parameter detail is needed because the schema already carries the full 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 names the stable sibling and defines this as 'Beta version of ask_pipeworx', a universal router with 5,798 tools, same arguments and response shape. It distinguishes this from ask_pipeworx by the experimental routing improvements while clarifying it is a working router, not a stub.

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

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

The description explicitly tells the agent to use it 'exactly like ask_pipeworx when you want the newest routing' and explains the current parity with the stable router. It does not give an explicit 'when not to use' or mention grounded alternatives, so it is clear but not fully complete.

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 convey read-only, idempotent, non-destructive, and open-world traits. The description adds substantial behavioral context beyond that: it details the success return shape, the exact refusal_reason enum values, that evidence is a verbatim quote, and the cost tradeoff of one extra LLM call. This fully discloses failure and success 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 dense but every clause serves a purpose: mode identity, routing scope, extraction behavior, return contract, refusal reasons, usage contexts, and cost comparison. Slightly longer than minimal, but not padded; front-loaded with the most important distinction (hallucination resistance).

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 compensates by specifying the response structure with evidence and refusal_reason variants. It explains when to use vs. the cheaper sibling, covers routing breadth, and details failure modes. For a complex tool with this scope, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the input schema fully documents the single required 'question' parameter and its aliases. The description does not add parameter-level detail, but the schema carries that burden completely; 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?

States a specific function: a 'Hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers only from fetched tool results. Explicitly distinguishes it from the sibling ask_pipeworx by the grounded extraction mechanism, so an agent can tell them apart immediately.

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?

Gives explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). Also names the alternative for casual lookups: 'prefer ask_pipeworx for casual lookups.' Clear selection criteria are fully stated.

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

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

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 already declare readOnlyHint and idempotentHint, but the description adds far more: account and paid-plan requirements, parallel decomposition and routing, findings packet fields, gaps[] for unanswered facets, a promise never to invent findings, contradictions[] on standard/thorough, citation fetchability, semantic excerpting, and latency expectations.

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

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

The description is long, but it front-loads essential gating information (account required, free alternative) and nearly every sentence carries substantive detail. The nested-parenthesis style and repeated comparisons to ask_pipeworx make it slightly less crisp than it could be, but it is still well organized.

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

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

With no output schema, the description compensates thoroughly: it enumerates the findings packet fields, explains citation_uri and hop, describes when gaps[] and contradictions[] appear, gives latency ranges, and explains semantic excerpting. An agent has enough context to invoke and interpret 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 100% schema coverage already documents both parameters, so the baseline is high. The description still adds useful semantics: depth:'thorough' requires a paid plan, standard adds a gap-recovery hop plus contradictions[], thorough adds an iterative lead-chasing pass, and broad/multi-part questions are explicitly acceptable.

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 is explicit: this is grounded multi-source research across Pipeworx's structured data sources in ONE call, and it explicitly says it is NOT open-web search. It also distinguishes itself from ask_pipeworx, making sibling differentiation clear.

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

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

It provides two explicit routing rules: use ask_pipeworx when not signed in, and use ask_pipeworx for a single lookup. It also says deep_research is best for broad/multi-part questions over structured data, and explains which depth tiers require what, so when-to-use guidance 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 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 read-only, idempotent, open-world, and non-destructive behavior, and the description adds substantial transparency beyond that: it discloses the USPTO API sunset with soft-fail behavior, the GDELT→GNews fallback, the expected empty FDA section for non-biologic companies, and the meaning of sources_used/sources_failed. It also pre-empts misreading empty results as bugs.

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

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

The description is long, but the tool is genuinely complex — it fans out across many sources and returns many fields. It front-loads the purpose with examples and routes the agent to the right choice, then systematically enumerates outputs. A slight deduction for density: it is a large single block where some repeated source mentions could be tightened.

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 carries the burden of explaining return values — and it does, covering resolved identity, recent_filings with URI shape, fundamentals ordering, patents, contracts, FDA products, hiring, news fallback, LEI, and the sources_used/sources_failed pair. Edge cases like missing FDA data and soft-failed patents are explicitly addressed.

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%, yet the description still adds real value: it explains that type 'company' and 'ticker' are interchangeable, gives exact value examples including zero-padded CIK, and clarifies what happens when a name resolves vs. a private company. The resolved_from/resolved_to and 'not a bare failure' notes are meaningfully beyond the 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 states a precise verb+resource: it builds a "full cross-source profile of a US public company in ONE parallel call," and immediately grounds it with concrete user phrasings like "tell me about X" and "company profile for Microsoft." It clearly distinguishes itself from narrower single-pack lookups by insisting this is the holistic, fan-out alternative.

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

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

The description gives explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also enumerates acceptable inputs (ticker, CIK, company name) and explains the private-company edge case, so an agent knows the runnable scope and the expected non-failure outcome when resolution fails.

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 readOnly/idempotent annotations already present, the description still adds substantial behavioral detail: BOTH modes run identical token-overlap matching, compatibility_warning and compatibility_codes can be non-empty even when matched_pairs>0, temporal_alignment null means 'could not be computed' not 'aligned', spreads are gross not net because Kalshi fees are unmodeled, and skipped counters disclose dropped comparisons. This goes far beyond the annotation surface.

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 densely packed with necessary safety semantics that no output schema covers. It is front-loaded with the core purpose, then uses capitalized labels like TWO MODES, RESPONSE, SAFETY FIELDS to keep structure navigable. A few sentences could be tightened, but each earns its place given the complexity of the 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?

There is no output schema, so the description must carry the full burden of explaining return values. It does: leg prices, top_spreads_pp, compatibility codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped_cross counters. The warning semantics are unusually complete for a no-output-schema tool.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description adds value by enumerating the exact topic shortcuts, explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and clarifying that both modes invoke the same matcher. This supplements the schema rather than merely repeating it.

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 opening sentence names a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This precisely distinguishes the tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison of equivalent outcomes rather than single-venue arbitrage. The two-mode explanation further clarifies the object being acted on.

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 documents TWO MODES with clear conditions: `topic` for 10 pre-mapped shortcuts, and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also cautions that pre-mapped topics often return warnings and are not necessarily tradeable. However, it never names sibling alternatives or states when to prefer a different tool, so the guidance is strong but not fully explicit about when-not-to-use.

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

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

Annotations already declare 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, idempotentHint, and openWorldHint. The description adds rich behavioral context: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI is unavailable, returns unresolved identifiers explicitly, and for ambiguous matches returns figi_candidates instead of asserting. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: examples, edge cases, degradation, input nuances, and source details. It is front-loaded with 'Use FIRST' and examples, and structured with SUPPORTED TYPES. No redundancy or 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 complexity (two types, multiple integration sources, edge cases like ambiguous matches and source unavailability), the description covers all necessary context. It explains the return behavior (labeled identifiers, unresolved list, figi_candidates) despite no output schema, and input requirements thoroughly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it explains how 'value' should be formatted for different entity types, including the critical note that for bonds you must pass the issuer name exactly as printed, not the full noun phrase. This is vital guidance not present in the schema.

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

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

The description clearly states it resolves a user-spoken name to canonical/official identifiers, with many examples and explicit mention of the two supported types (company, drug). It distinguishes itself as the first step for name-to-ID needs, making it distinct from siblings like entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID', which is a strong when-to-use signal. It also provides detailed input formatting guidance (e.g., for bonds pass issuer exactly as printed). However, it does not name specific alternative tools for when not to use it, though the 'Use FIRST' statement implicitly covers that.

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.