exchange

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

Annotations declare readOnly, idempotent, and openWorld hints, and the description adds complementary behavioral context: the default model is free, using Anthropic requires a BYO key and direct payment, and it returns per-model objects plus a combined view. It also implies external API calls. No contradiction with annotations exists, and the added cost and dependency details go beyond what annotations alone 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 sentences, front-loaded with the primary action, then defaults/cost, then return format, then use cases. Every sentence carries useful information with zero redundancy or fluff. It is efficiently structured and easy to scan.

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 appropriately describes the return format ('per-model {score, confidence, signals, raw_response} + a combined view') and mentions the free default model. It covers all key aspects: purpose, input flexibility, cost implications, output, and use cases. Nothing essential is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already thoroughly documents all parameters, including `_apiKey` requirements and the meaning of `context`. The description repeats some of this (e.g., 'pass `_apiKey` to also probe Anthropic') but doesn't add substantial new parameter-level meaning 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+resource: 'Probe one or more LLMs... and score visibility (0-100) per model.' It clearly states the core function and provides a concrete output structure. This distinguishes it from siblings like ask_pipeworx (which likely answers questions about internal data) and scan_competitor_ai_presence (competitor-focused), while the use cases (AI-marketing audits, pre-launch checks) further narrow the 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 explicitly lists practical use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternatives (e.g., scan_competitor_ai_presence), so it falls 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which covers the safety profile. The description adds valuable behavioral context: it routes to a huge tool universe, fills arguments, returns structured answers with stable citation URIs, works on every tier, and makes one fast call. This goes beyond what annotations alone convey, though it doesn't mention potential latency or failure modes.

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 (about 200 words) but every sentence serves a purpose: opening directive, domain list, usage cases, examples, escalation paths, and warnings about alternatives. It is well-structured and front-loaded with the most critical guidance, though a slightly tighter version could trim redundancy without losing meaning.

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 compensates by stating that the tool returns structured answers with stable pipeworx:// citation URIs. It also explains routing behavior, tier compatibility, and when to use alternatives. Combined with the annotations, this gives an agent sufficient context to call the tool correctly, though a bit more detail on the response format could be ideal.

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

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

Schema coverage is 100%, and the description adds value by illustrating the acceptable question formats with diverse examples ('current US unemployment rate', 'Apple's latest 10-K', etc.). It also clarifies that the parameter is a natural-language request, which helps an agent frame the input correctly. The schema already provides aliases, so no redundancy.

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 a specific verb ('ask', 'routes', 'returns') and resource (real-world data from 5,581 verified sources), and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It lists concrete domains (SEC, FDA, FRED, etc.) and provides examples. An agent can immediately understand what this tool does and how it differs.

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 'PREFER OVER WEB SEARCH' and gives a detailed list of when to use it (factual questions, current/historical data, 'what is', 'look up', etc.) and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). This is comprehensive, leaving little to inference.

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 state readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: that the tool is an experimental edge, that no candidate is currently active, that the last candidate was retired on a specific date, and that it 'falls back to nothing' because it is a fully functional router. This is honest about the beta nature and current operational state.

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 and front-loaded with the tool's identity as a beta version, then current status, then usage guidance. It includes several specific details like the tool count and retirement date, which are informative rather than filler. It is slightly dense but every sentence contributes to operational understanding.

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 companion tool to ask_pipeworx, the description provides enough context: identical arguments and response shape, current candidate status, usage guidance, and reassurance that it is a full router. Since there is no output schema, mentioning that the response shape matches ask_pipeworx covers return expectations. The main missing piece is a standalone description of what the returned answer looks like, but the sibling reference mitigates that.

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

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

Schema description coverage is 100%, with each parameter clearly defined and the main 'question' parameter describing its aliases. The description adds that the tool takes the 'same arguments' as ask_pipeworx, which is helpful for transfer, but it does not need to restate parameter meanings already present in the schema. It meets the baseline without significantly extending parameter-level 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 identifies the tool as 'Beta version of ask_pipeworx' and calls it an 'identical universal router' with the same 5,581 tools and response shape, which conveys that it routes natural-language requests to tools. It also distinguishes it from the stable sibling by labeling it the experimental edge with candidate routing improvements. However, it does not fully define the underlying routing behavior independently; it leans on ask_pipeworx for that meaning.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes the current state when no candidate is active, so it matches ask_pipeworx exactly. This gives an agent a concrete condition for choosing this tool over the stable sibling and clarifies that it is a full working router, not a fallback-only wrapper.

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 well beyond the annotations by detailing the grounded-extraction behavior, the exact success response shape, and the explicit refusal reasons such as 'not_in_source' and 'data_truncated.' It also discloses that it will not answer unless the tool result directly contains the answer, which is valuable behavioral context. This is consistent with the readOnly, idempotent, and openWorld 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 dense but every sentence contributes: it explains what the tool does, how it works, what it returns, when to use it, and when not to use it. The most important differentiators (grounded, refusal behavior, high-stakes use) are front-loaded, and the cost tradeoff is placed at the end without bloat.

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

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

Even without an output schema, the description fully specifies the success and refusal return contracts, the conditions triggering refusal, and the decision boundary versus ask_pipeworx. Combined with annotations covering read-only and open-world behavior, the agent has everything necessary 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 description coverage is 100%, with all parameters documented as aliases for a single natural-language question parameter, so the schema already carries the semantic weight. The description adds no parameter-specific detail, but none is needed given the complete schema. 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 identifies a specific verb and resource: it is a 'hallucination-resistant answer mode' that grounds answers in tool results. It clearly distinguishes itself from ask_pipeworx by explaining that it extracts answers only from fetched data and returns refusals when data is insufficient. The stated use case for quoted, cited, or high-stakes answers further sharpens its 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 explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative, ask_pipeworx, and gives a concrete routing rule: 'prefer ask_pipeworx for casual lookups,' including the cost tradeoff of one extra LLM call.

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, idempotentHint), the description reveals extensive behavioral details: resolver contract with confidence levels, low-confidence short-circuit suppressing analysis, closed-market status, illiquid wide-spread marker, cancellation-rule parsing with ev_impact, news fallback on GDELT 429, and parent_event extractor. This is rich, non-obvious context.

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

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

The description is a single dense wall of text with no paragraph breaks or bullet points, making it hard to scan. It is over-specified and not front-loaded; important safety caveats (resolution-rule risk, low-confidence short-circuit) appear late. While all content is relevant, structure and length are poor.

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 the lack of an output schema, the description thoroughly explains response shapes (market/analysis/evidence), statuses (low_confidence_match, market_closed_or_inactive), matching contract, parent_event extraction, and news fallback mechanics. No important behavior is left unexplained.

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 3 parameters (100% coverage), so baseline is 3. The description adds extra semantics for the 'market' parameter by clarifying slug/URL/question text forms and explaining the resolver contract (match_confidence, match_score, alternatives, suggestions) that interprets input, which goes 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly stating a specific verb (research) and resource (Polymarket bet). It distinguishes itself from sibling tools by emphasizing the one-call fan-out, classification, and evidence packet, and includes classifiers and fan-out examples.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This gives clear context for when to invoke the tool, but it does not explicitly mention alternatives or state when not to use it, so it falls 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL for company, FAERS/FDA for drugs), specific metrics (revenue, net income, cash, debt; adverse-event counts, approval counts, trial counts), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. These details go far beyond the annotations and set proper 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 front-loaded with trigger phrases and core function, then details type behavior and output. Each sentence adds operational value, covering usage, data sources, edge cases, and efficiency. While somewhat verbose, it is well-structured and every sentence earns its place, so a 4 is appropriate rather than 5.

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 specifying return contents (paired data + pipeworx:// citation URIs), sorting behavior, and data sources. It also covers edge cases like off-calendar fiscal years and explicitly notes the tool replaces 8–15 sequential lookups. This is complete for a complex comparison tool with strong annotation coverage.

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

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

Schema covers both parameters with 100% description coverage, giving baseline 3. The description enriches this with concrete examples for values (e.g., 'AAPL', 'MSFT', 'ozempic', 'mounjaro'), clarifies tickers/CIKs vs drug names, and links each 'type' to the data it retrieves. This goes beyond the schema's basic enum and array descriptions, meriting a 4.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with verb 'compare' and resource 'entities' plus examples of trigger phrases. It clearly distinguishes itself from sequential single-pack lookups, making its purpose specific and differentiated from siblings like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives concrete examples of when to use it (e.g., 'which is bigger', 'rank these companies'). It also specifies type-dependent behavior (company vs drug), providing clear context for use versus alternatives.

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

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description adds useful context that it uses current exchange rates and returns both the converted amount and the rate, which goes beyond the annotation 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 two concise sentences that front-load the action and result, with no redundant information. Every word contributes meaning.

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

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

For a simple tool with three well-documented parameters, strong annotations, and an output schema, the description fully covers what the tool does, its scope, and its return values. No critical gaps exist.

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

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

Schema coverage is 100% with clear descriptions for each parameter (from, to, amount). The tool description reinforces the meaning but does not add additional parameter details, which is acceptable given the high 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 uses the specific verb 'Convert' and names the resource ('amount from one currency to another'), clearly distinguishing it from sibling tools like get_rate or get_historical_rate by emphasizing 'current rates' and the return of the converted amount plus exchange rate.

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 phrase 'at current rates' clearly implies this is for live conversions, not historical ones, which provides usage context. However, it does not explicitly mention alternatives like get_historical_rate, so it stops short of full exclusion 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 description adds a lot beyond the readOnlyHint/openWorldHint annotations: it never invents facts, returns a findings packet with a hop attribute, uses gap arrays, runs second-pass revival for unanswered pieces, and explains timing. This is rich, honest behavioral disclosure that the annotations alone cannot convey.

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

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

Long but organized; key facts (account required, not open-web, gaps[]) are front-loaded)Skip the parenthetical about the trailing en-dash typo; irrelevant. Everything serves a purpose, though a few parentheticals and repeated clarifications could be tightened. Still clearly superior to a one-liner.

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

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

Covers when to use, when not, what it returns (verbatim evidence, confidence, citations, gaps), how it behaves across depths, and the critical 'never invents' caveat. Nothing an agent needs to decide or invoke properly 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?

The schema already defines `question` and the `depth` enum, so baseline is 3. The description goes further by explaining why broad questions are fine (decomposition) and what each depth level does (quick=minimal, standard=gap recovery + contradictions, thorough=multi-pass iterative). That pushes it to a 4.

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 a specific verb and resource ('Grounded multi-source research across PipeWorx's structured catalog'), states the deliverable (findings packet with citations and gaps[]), and explicitly contrasts itself with ask_pipeworx. An agent can tell exactly when to pick it: broad, multi-faceted structured-data 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?

Spells out when to use (broad/multi-part, financial data) and when NOT to use (breaking news, general web questions), and names the sibling alternative (ask_pipeworx) plus the reason (structured catalog vs. real-time search). No ambiguity left.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full schemas, and that results are 'ready to call directly' with no second lookup. This 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 well-structured and front-loaded: starts with the core purpose, then usage, then return behavior, then the 'call first' directive. The list of domains is a bit long but earns its place, and every sentence adds value without redundancy.

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

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

For a simple tool with 1 required parameter and no output schema, the description is complete: it explains what the tool does, when to use it, what it returns (top-N tools with schemas), and how to invoke it. No significant gaps remain.

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

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

Schema description coverage is 100%, including detailed descriptions for query and aliases, so the baseline is 3. The description's mention of 'describing the data or task' adds no new semantics beyond what the schema already provides for the query parameter.

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

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

The description clearly states 'Find tools by describing the data or task' – a specific verb+resource that distinguishes this as the meta-discovery tool. It provides a concrete list of domains it covers, and the 'Call this FIRST' directive separates it from sibling tools like deep_research or search_within.

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

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

Explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use it and implies when not to (when you already know the exact tool).

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

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

Annotations already declare read-only/idempotent; the description adds concrete behaviors: 'up to 5' filings, 'LATEST 10-K' sorted, patents 'soft-fails until reactivated', and GDELT→GNews fallback, plus the parallel-call fan-out across sources.

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 examples, function, output fields, and caveats into one paragraph; every clause serves a purpose, though front-loading with queries could be tightened with a direct action verb first.

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 multi-source fan-out and lack of output schema, the description fully covers inputs, outputs, fallbacks, and limitations, sufficient for an agent to decide and invoke.

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

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

Schema already describes both params with 100% coverage; description reinforces value format with examples 'AAPL' and '0000320193' and clarifies the alternative path for names, adding practical formatting nuance beyond schema.

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

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

The description explicitly defines the tool as a 'full cross-source profile of a US public company in ONE parallel call' and lists the exact return fields, clearly distinguishing it from siblings like resolve_entity (name resolution) and compare_entities (comparison).

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

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

It states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly says 'names not supported (use resolve_entity first if you only have a name),' providing both when-to-use and alternatives.

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

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

Annotations already disclose destructiveHint=true and readOnlyHint=false, so the description adds context (e.g., clearing sensitive data) but no additional behavioral traits. It is consistent with annotations, so no contradiction.

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

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

The description is two sentences, front-loaded with the action, and contains no wasted words. It efficiently conveys purpose, usage, and related tools.

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 destructive tool with strong annotations, the description covers the core action, usage triggers, and sibling relationships. No output schema exists, so return values need not be explained. The description is complete.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description does not add information 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 states 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from sibling tools 'remember' and 'recall'. Its function is 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 usage conditions are provided ('context is stale, task is done, or clear sensitive data') and related tools are mentioned ('Pair with remember and recall'). However, it lacks explicit when-not-to-use guidance or alternatives, so it does not fully earn 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 declare read-only and non-destructive, and the description adds behavioral context: fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt format. This goes beyond the annotations by explaining the processing steps and output form.

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, front-loaded with the primary action, followed by process and use cases. No fluff, 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 read-only generation tool with robust annotations and fully documented parameters, the description provides sufficient context. Output schema is absent but the description explicitly states the output format ('standard llms.txt markdown format', 'single text blob'), which is adequate.

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

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

Schema coverage is 100% and both parameters are well described in the schema. The description mentions 'any URL' and 'key links' but does not add extra detail beyond the schema. Per guidelines, high schema coverage sets a baseline of 3.

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

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

The description states a specific verb ('Generate') and resource ('a production-ready llms.txt file') for any URL, and clearly distinguishes from sibling tools by focusing on file generation rather than scanning or visibility checks. It also explains the purpose (AI crawler indexing) and output format (standard llms.txt markdown).

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 lists three use cases: getting a client's site indexed, drafting for a project, and auditing a competitor. Does not explicitly mention when not to use or name alternative tools, but the context is clear enough for an AI agent to select 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns codes and full names, but this is minimal beyond what annotations provide. No contradictory behaviors disclosed.

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 short sentences, front-loading the primary action ('List all supported currencies') and then adding the usage context. Every word 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?

With no parameters, an output schema, and comprehensive annotations, the description fully captures the tool's purpose and usage context. Nothing further is needed for a simple list operation.

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 tool accepts zero parameters, so the description does not need to explain parameter semantics. Per the baseline for 0-param tools, this rates a 4.

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 'List all supported currencies with codes and full names', which is a specific verb-resource pair. It also positions it as a reference tool for verifying codes before conversion or rate checks, distinguishing it from siblings like get_rate and convert.

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

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

The description explicitly says 'Use to verify currency codes before converting or checking rates', providing clear context for when to use this tool. It implies a distinction from conversion/rate tools but does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by disclosing the return behavior ('Returns the historical rate and date') and reiterating the date format (YYYY-MM-DD), which provides context beyond the structured annotations. No contradictions exist.

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

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

The description is a single, well-structured sentence that front-loads the primary action and resource, then adds the key constraints and return info. Every word earns its place; no filler or redundancy. It is appropriately concise for the tool's simplicity.

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 three parameters, a fully described schema, and an output schema mentioned, the description is complete. It covers the purpose, the input date format, and the return values. Annotations cover safety, so no additional behavioral context is needed. The tool is well-specified for an agent to invoke correctly.

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

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

The input schema provides 100% description coverage for all three parameters with examples, so the baseline is 3. The description adds minimal extra meaning by mentioning 'between two currencies' (clarifying from/to) and the date format, but it mostly restates what the schema already contains. It does not introduce any new parameter insights.

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 specific function: 'Get the exchange rate between two currencies on a specific date'. It uses a specific verb ('get') and identifies the resource (historical exchange rate) and the key differentiator (specific date). This distinguishes it from siblings like 'get_rate' (current rate) and 'convert', making the purpose unambiguous.

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

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

The description clearly establishes when to use this tool (for historical rates on a specific date) by emphasizing the date parameter. It does not explicitly mention alternatives like 'get_rate' for current rates, but the context is clear enough that an agent can infer the use case. No exclusions or when-not-to-use scenarios are stated, which is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating the return value includes rate and timestamp, which is beyond the annotations. No contradiction.

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

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

Two concise sentences, front-loaded with the primary action, and no wasted words. Each sentence contributes essential information about scope and return value.

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

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

For a simple, read-only tool with full schema coverage, annotations, and an output schema, the description is complete. It specifies the input (two currencies), the output (rate and timestamp), and aligns with the current-rate context.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides example currencies (USD, EUR) but does not add semantic meaning beyond the schema descriptions for 'from' and 'to'.

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

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

Description clearly states the verb 'Get' and resource 'current exchange rate between two currencies', with examples. It is distinct from siblings like get_historical_rate and convert, focusing on current 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 implies usage for current rates via the word 'current', but does not explicitly mention when to avoid it or name alternatives like get_historical_rate for historical data. Clear context but 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context by specifying the return fields and clarifying that only active subscriptions are returned by default, which complements the annotations without repeating 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 two sentences, with the main action front-loaded and no wasted words. It immediately states what the tool does, lists key return fields, and ends with practical usage guidance.

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 low complexity (one optional parameter), rich annotations, and the explicit list of return fields, the description covers all necessary context. It tells the agent what the tool returns, when to use it, and how the single parameter affects results.

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

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

Schema description coverage is 100% for the single parameter include_inactive, which is fully explained in the schema. The description does not add additional parameter semantics beyond what the schema already provides, 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 uses a specific verb 'List' with a clear resource 'the caller's active subscriptions' and enumerates the returned fields. It clearly distinguishes from sibling tools like subscribe and unsubscribe by focusing on review of existing subscriptions.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly mention when not to use it or name alternatives, but the context is clear and sufficient for the agent.

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

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

The description adds rich behavioral context beyond the annotations: the two-phase feedback flow with claim_token, the daily rate limit (5 per identifier per day), and the reminder not to paste end-user prompts. The annotation set (all false) does not contradict the description, and the description meaningfully supplements it.

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?

While longer than average, every sentence earns its place: the purpose is front-loaded, the when-to-use clauses are compact, and the edge cases (different MCP server, claim_token, rate limit) are each addressed in one focused sentence. No fluff 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?

With no output schema, the description sufficiently covers what happens on filing (returns claim_token) and how to read later status. It also covers prerequisites (none), and the constraints on message content. For a feedback tool with four parameters, it is fully self-contained.

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

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

Schema coverage is 100%, but the description adds significant value: it explains how to use claim_token (including a code example), warns against pasting end-user prompts, and ties the message to specific Pipeworx tools/packs. This goes far beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings (ask_pipeworx, subscribe, etc.) by being the feedback channel, and it explicitly scopes its use to tools served by this Pipeworx connection.

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

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

Provides explicit when-to-use guidance (bug, feature/data_gap, praise) and when-not-to-use (tools from a different MCP server, directing users to file with that server instead). Also explains the claim_token workflow and rate limit, offering clear context for how to interact with the tool.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description goes further by explaining data provenance (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which provides useful context beyond the annotation defaults.

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 well-structured: the first sentence states the core purpose, followed by a list of use cases, then data provenance and caching. Every sentence adds value and there is no redundant 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 simple tool with one optional parameter and no output schema, the description covers the return contents (top tools, packs, call volume), window options, use cases, context, and caching. It lacks a detailed output shape but hints at the data tuple (pack, tool, count), making it reasonably 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?

The sole 'window' parameter is fully documented in the schema with enum values and guidance on short vs. long windows. The description reinforces the available windows but does not add significant extra meaning beyond what the schema already provides.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a selectable window, which is a specific and distinct purpose. It differentiates from sibling tools like discover_tools by emphasizing real-time aggregate agent usage rather than static discovery.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tools, and aligning with agent needs), giving clear context on when to use. However, it does not explicitly mention when not to use or name alternative tools, so it falls short of a perfect 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses internal logic: monotonicity checks, partition placeholder filters (>20% placeholder returns null), Jaccard similarity threshold (≥0.30), fill-check pricing against live CLOB depth, and signal emission threshold (>3pp). It even explains how `skipped_low_similarity` behaves. This is far more transparent than typical tool descriptions and complements 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 long but well-structured with section labels (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). It front-loads the core purpose and mode selection. Every sentence adds substantive detail; however, it is dense and could be trimmed slightly without losing critical information. Still, it earns its length for a complex 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?

Despite having no output schema, the description covers the response structure (opportunities[], partition_check, fill_check), explains edge cases (null arb signal, thin legs), and refers to sibling tools for related functionality. It gives a complete picture of the tool's behavior across all modes, making it highly actionable for 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?

The input schema already provides 100% coverage with clear descriptions for `event` and `topic`. The description adds value by enriching semantics with concrete examples (e.g., 'fed-decision-may-2026'), accepting full URLs, and explaining how each param is used in the underlying algorithm ('walks child markets', 'searches related events'). Since schema coverage is high and description augments rather than repeats, a 4 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 purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (`trending_scan`, `event`, `topic`) with specific use cases, making it easy to differentiate from sibling tools like `polymarket_edges` or `polymarket_fill_risk`.

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

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

The description gives explicit guidance on when to use each mode: no args for trending scan, `event` recommended for a specific market, `topic` for cross-event scanning. It also names an alternative tool (`polymarket_fill_risk`) for custom sizing, and explains when NOT to trade (realizable_edge_pp ≤ 0). This is exemplary usage guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses caching behavior (1-hour at KV level), response diagnostics for empty results, a 24h price-move warning, and the Fed signal caveat with explicit unreliability reasoning. This adds substantial behavioral context an agent wouldn't know 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 long but information-dense, front-loading the core purpose and then providing necessary detail about model families, response structure, and knobs. While it could be reorganized with more headings, every sentence carries operational content that aids correct invocation and interpretation.

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 goes beyond the minimum by specifying the full response envelope (by_segment, fed_candidates/fed_note, _diagnostics), the per-opportunity fields, and the reasons a segment might be empty. It also documents parameter interactions and the Fed data limitation, making the tool fully usable without 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?

The schema already covers each parameter at 100%, so the baseline is 3. The description adds value by grouping knobs into tradeable-edge filters and explaining inter-parameter relationships, such as why min_kelly doesn't apply to partition_overround and how min_partition_leg_kelly targets per-leg Kelly instead.

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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This directly states what the tool does and distinguishes it from sibling Polymarket tools by emphasizing the Pipeworx disagreement signal and the intended use case for daily bet discovery.

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 phrase 'Built for "what should I bet on today"' gives a clear intended use case, and the description explains the types of opportunities (model-driven, structural arbitrage, concentrated longshot) and filtering knobs. However, it doesn't explicitly name alternative tools to prefer instead, or state when not to use it, making the usage guidance clear but not exhaustive.

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

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

Annotations declare read-only, open-world, and idempotent behavior, and the description adds substantial non-trivial context: snapshot TTL limits, cache-miss snapshot writing, signed edge_pp_net (negative = SELL YES), and interpretation of gaps in snapshot_dates. It also clarifies decay uses daily closes, not intraday data, and notes the median lifespan as a 'competition clock'.

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?

Despite its length, the description is efficiently structured with labeled sections (Args, RESPONSE, LIMITS) and front-loads the core purpose. Every sentence contributes meaning—explaining response fields, data caveats, and usage context—making the length appropriate for the tool's complexity.

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

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

With no output schema, the description thoroughly documents all return components: tracked[] with time-series, trend, decay; expired[] with lifespan; and snapshot_dates[] with gap interpretation. It also touches on data depth, freshness, and the computation basis, making it self-contained for an agent to understand full behavior.

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 specifies both parameters fully, including defaults and clamp ranges. The description's 'Args' section reiterates this without adding new semantic detail (e.g., examples or parameter interplay). With 100% schema coverage, the description adds marginal value, hence the baseline of 3.

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

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

The description explicitly states the tool's purpose as 'edge persistence and decay telemetry' and answers the question 'how long has this edge existed and is it shrinking?', clearly distinguishing it from the sibling polymarket_edges tool which provides current edge snapshots. The mention of time-series vs. single-snapshot analysis adds specificity.

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

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

The description implies usage context—this tool is for analyzing edge persistence/decay over time, as opposed to the direct polymarket_edges snapshot. It doesn't explicitly name alternatives or exclusions, but the 'built from daily polymarket_edges snapshots' phrasing and response semantics provide enough guidance for when to choose it.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, but the description adds substantial behavioral context: it 'walks the ladder', exposes partial-fill risk, names 'forced_directional_risk', and clarifies that theoretical overround on thin books is not capturable. This goes well beyond the annotation safety profile.

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

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

The description is long but densely structured: purpose first, then REQUIRES, then mode-specific details, then usage directive. Every segment contributes essential information for a complex tool. It could be tightened slightly, but the structure is logical and front-loaded.

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

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

With no output schema, the description carries full responsibility for explaining returns—and it does so in detail for both modes, listing all key output fields (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.). It also covers prerequisites, size interpretation, and failure modes, making it complete for the tool's complexity.

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

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

Though schema description coverage is 100%, the description adds crucial meaning: it defines the mode-selection semantics (market vs event), explains the side enum values for each mode (including auto-default), and distinguishes size_usd as max spend vs target proceeds in single-market mode and as settlement notional in basket mode. This is far more than the baseline.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, and by describing the two distinct modes (single-market and basket).

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the alternative risk (partial basket fills create unhedged positions), making the decision context 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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral detail: the compatibility_warning with two specific cases, temporal_alignment semantics, skipped_cross_type/subtype counters, and the reality that most shortcuts return warnings. This is far beyond the baseline, disclosing edge cases, failure modes, and interpretation of output.

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 well-structured, with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence conveys unique information, but the length is substantial — some sentences could be tightened without losing meaning. It front-loads the core purpose early, so it earns a strong score, but slight verbosity prevents a 5.

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 (cross-venue matching, safety warnings, temporal alignment, many skipped-leg counters) and the absence of an output schema, the description is exceptionally complete. It explains what fields will appear (matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type) and how to interpret ambiguous cases. No critical aspect is left unexplained.

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

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

The input schema has 100% coverage for three parameters, but the description enriches them by explaining how they interact: `topic` auto-fetches matching events, while explicit tickers/slugs create custom pairings and 'override the topic-mapped' side. It also explains the response format and what each parameter influences in the output, adding understanding beyond raw schema descriptions.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the exact resource (cross-venue spread) and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on single venues. The two modes and response details further cement the specific function.

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

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

The description explicitly lays out TWO MODES — `topic` with pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` — giving concrete when-to-use scenarios. It also warns when NOT to trust the output: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' This goes beyond mere context to actionable 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 disclose readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those: omitting the key lists all saved keys, and results are scoped to an identifier (anonymous IP, BYO key hash, or account ID). This explains important behavioral nuances not covered by annotations. It does not contradict annotations.

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

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

The description is three sentences: first states the core action, second gives practical use cases, third explains scoping and pairing with siblings. Every sentence earns its place, no redundant or vague wording. It is front-loaded with the primary behavior.

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

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

For a simple 1-parameter, 0-required tool, the description covers the action, how the parameter behaves when omitted, scoping, and related tools. Annotations handle safety, and the schema covers the param. No output schema exists, but the return behavior (list vs. value) is adequately implied. The tool is fully contextualized in the larger tool set.

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 has 100% coverage with a clear description of the optional 'key' parameter ('omit to list all keys'). The tool description reinforces this behavior and provides example keys (user_research_topic, etc.), but does not add new semantic details beyond what the schema already offers. Baseline 3 is appropriate since the schema carries the burden.

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 retrieves a value saved via remember or lists all saved keys. It uses specific verbs and resource (memory key/value) and distinguishes itself from sibling tools like remember and forget. Examples of use cases further clarify the 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?

It explicitly says to use when you need previously stored context (user's ticker, address, research notes) and mentions pairing with remember (save) and forget (delete). It even notes that using this avoids re-deriving context from scratch. This provides clear when-to-use guidance without needing an explicit exclusion clause.

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 explicitly discloses that mark_read:true modifies the read state of returned events, which is a side effect. This directly contradicts the readOnlyHint=true annotation, making the description misleading about the tool's mutability. Therefore the score is 1, and annotation_contradiction is flagged.

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 appropriately sized: it covers purpose, return format, filtering, and side effects in under 40 words while remaining structured and front-loaded. No filler exists.

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

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

The description is complete for a read-oriented alert tool: it specifies return payload fields, filtering, pagination, and the side effect of mark_read. It even mentions alternative access, covering the main aspects an agent would need to invoke it correctly.

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

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

The input schema already covers all parameters at 100%, but the description adds valuable semantics by explaining the meaning of type with an example ('sec_8k'), since as an ISO timestamp, and the mark_read behavior. This enhances understanding beyond the schema, so a 4 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 pulls fired events from the subscription feed and returns recent alerts, with a specific verb and resource. It distinguishes itself from sibling tools by focusing on reading alert events rather than managing subscriptions.

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

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

The description provides clear context for when to use the tool (checking recent alerts) and even mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly name sibling tools as alternatives or exclusion criteria, so it is slightly below a perfect score.

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?

Even though annotations already declare readOnly/openWorld/idempotent non-destructive behavior, the description adds substantial behavioral detail: underlying data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), rate-limit fallback logic, and the soft-failure due to PatentsView API sunset. It also discloses output structure and citation URIs.

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

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

The description is dense and packed with useful information, though it is a long run-on sentence. Every clause adds value, and the structure is acceptable for a multi-source tool, but a more bulleted or segmented layout would improve scannability.

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

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

Given there is no output schema, the description compensates by explicitly stating the return shape (changes[], total_changes, citation URIs) and covering all major behavioral aspects: sources, fallback, date formats, and alternative tool. 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 description coverage is 100%, so the baseline is 3. The description restates the `since` formats and value examples already present in the schema, adding little new parameter-specific meaning. It does reinforce typical usage ('30d' or '1m') but not enough to exceed the baseline.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months', with specific verbs like 'Fans out' and explicit scope. It also distinguishes itself from the sibling tool entity_profile by contrasting dynamic changes with 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?

Provides explicit usage context through query examples ('What's new with X', 'latest on Y') and gives a direct when-not-to-use directive: 'Use entity_profile instead when you want the static profile'. This makes the selection boundary 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This adds valuable 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?

Four sentences, front-loaded with the core purpose. Each sentence adds unique value: purpose, when-to-use, persistence semantics, and sibling pairing. No waste.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, persistence, and related tools. It is self-sufficient and 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?

The schema already covers both parameters fully (100% coverage), so baseline is 3. The description doesn't add parameter details beyond mentioning 'key-value pair', but schema descriptions suffice.

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 saves data for later reuse, using a specific verb ('Save') and resource ('data'). It differentiates from sibling tools by explicitly pairing with recall and forget.

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

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

Provides explicit when-to-use guidance ('when you discover something worth carrying forward') and names alternatives ('Pair with recall to retrieve later, forget to delete'). This makes usage 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows the tool is safe, idempotent, and non-destructive. The description adds valuable behavioral details beyond annotations: 'Each call cascades through several lookup endpoints internally,' 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return,' and that unresolved identifiers are stated explicitly under `unresolved`. No contradictions with annotations.

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

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

The description is front-loaded with example queries and a clear purpose statement. It is well-structured, first explaining the general use, then detailing supported types with bullet-like sections. However, it is verbose in places (e.g., 'every identifier is labelled with the source that established it' could be shortened). The length is justified by the complexity, but conciseness could be improved by trimming repetitive details.

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

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

Given the tool's complexity (two entity types, multiple sub-identifiers, external dependencies, no output schema), the description is comprehensive. It explains what identifiers are returned for each type, how graceful degradation works, what happens with ISINs, and that unresolved identifiers are included. For a tool with no output schema, the description carries the full burden of explaining return values, and it does so thoroughly. The agent can infer the return structure and edge cases.

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

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

Schema coverage is 100% with both parameters (`type` and `value`) described. The description goes far beyond the schema by explaining what each type returns (e.g., for company: CIK, ticker, LEI, FIGI, ownership chains; for drug: RxCUI, ingredient, brand, citation). It also provides example inputs (AAPL, CH0038863350, ozempic) and clarifies that ISINs resolve to the legal entity via GLEIF. This adds rich semantic context beyond the enum and string 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 concrete example queries ('What's the ticker for…', 'find the CIK for…') and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes the tool from siblings by noting that it replaces 2-3 manual lookups and should be used first when a name is known but an ID is needed. The supported types (company, drug) and their specific output identifiers are clearly enumerated, leaving no ambiguity about what the tool does.

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 a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that using resolve_entity replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when NOT to use this tool (e.g., if you already have an ID, use entity_profile instead), nor does it contrast with sibling tools like compare_entities or entity_profile. The guidelines are strong but lack explicit exclusions or alternative tool recommendations.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, supports multiple models (with optional Anthropic API key), and returns a ranked list with score/confidence/signal density. This goes 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 three focused sentences, beginning with the primary action and ending with return details. No wasted words; front-loaded with the core function.

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 multi-probe ranking tool, the description adequately covers parameters, return values (ranked list with metrics), and a concrete use case. No output schema exists, but the described return format is sufficient for selection. Minor gaps include no mention of rate limits or failure behavior, but these are not critical.

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 every parameter has a description. The description further clarifies that the first entity is treated as the 'subject' for narrative, and provides context on models ('workers-ai' free default vs 'anthropic' requiring key), adding semantic value beyond the schema.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. This is a specific verb+resource that distinguishes it from the single-entity sibling ai_visibility_check.

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

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

The description provides clear context for when to use the tool ('competitive AI-marketing audits') and implies the multi-entity scenario. It does not explicitly state exclusions or alternatives, but the use case is well-illustrated with an example query.

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 readOnly/idempotent annotations, the description discloses important behavioral traits: it is a composite fan-out call, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. It also states the ecosystem limitation and output shape.

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 highly structured, leading with purpose, then use cases, then return fields, then ecosystem constraints, and finally failure behavior. Every sentence provides operational value, and no fluff is present.

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 composite tool with no output schema, the description is remarkably complete: it details the return block fields, per-advisory details, links, alternative versions, ecosystem scope, failure modes, and latency expectations. This is sufficient for an agent to correctly invoke and interpret the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little parameter-specific meaning beyond the schema; it confirms the purpose but does not explain parameter semantics in more depth than the already-detailed schema descriptions.

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

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

The description starts with a specific, composite purpose: 'should I add this npm package to my project' check in ONE call, and clearly enumerates the fan-out sources (deps.dev and bundlephobia) and the data categories. It is unambiguous and distinguishes this tool from siblings by its scope and aggregation.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Description discloses technical behavior beyond annotations: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flag, and every passage carries an offset for quote verification. This adds substantial behavioral context without contradicting 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 front-loaded with the core action, then usage guidance, then pairing, then implementation details. Each sentence contributes distinct information without redundancy. It is slightly long but 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?

Despite no output schema, the description clarifies the return format (top-N passages with offsets and scores). It also explains input requirements, the use case, and technical constraints (truncation at 200K chars). The description is complete for a semantic search 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 already describes all 3 parameters with 100% coverage. The description adds illustrative context (e.g., 'text you already pulled' and example queries) but does not significantly enhance parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description states 'Semantic search INSIDE a fetched record'—a specific verb and resource. It also specifies the output (top-N passages with character offsets and similarity scores) and distinguishes from siblings by pairing with ask_pipeworx_grounded for a fetch-then-ground workflow.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the context-saving benefit. It also names the sibling ask_pipeworx_grounded and describes the workflow: fetch with the gateway, ground over relevant passages instead of the whole document, providing clear alternatives.

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

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

Discloses important behavioral traits beyond annotations: authentication requirement, sms phone verification with 10/day cap, webhook auto-disable after 10 consecutive failures, and one-time-only webhook signing secret. These details go well beyond the readOnly/idempotent/destructive flags in annotations.

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

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

The description is lengthy but every sentence serves a distinct purpose. It is front-loaded with the primary purpose and return value, then organizes types and delivery channels logically. No redundant or filler 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?

Given the complexity (multiple types, nested objects, delivery channels) and absence of an output schema, the description covers auth, return value (subscription id), webhook secret retrieval, delivery constraints, and example parameters. It is fully 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 describes all parameters comprehensively, including type-specific examples. The description adds value by clarifying constraints like verified phone and webhook private-host rejection, which are not in the schema descriptions.

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

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

The description begins with a specific verb 'Create' and resource 'proactive monitoring subscription', clearly stating the tool's core function. It lists supported subscription types and delivery channels, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

Provides clear context: requires OAuth account, explains feed vs email vs sms, and mentions an alternative pull method (recent_alerts or registry URL). It lacks explicit contrast with sibling tools, but the context is strong enough for an agent to infer when to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: it draws from the 'live catalog of thousands of tools', returns category-bucketed examples, and topic narrowing. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads natural language example queries, then explains output, arguments, and usage context. Every sentence adds value, with 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 with no output schema, the description is complete: it explains what to expect (category-bucketed examples, exact tool shapes), how to call it (optional topic), and when to use it (first step, meta-tool guidance). No gaps remain.

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

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

Schema coverage is 100% for the single optional topic parameter. The description enriches it by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a 'cross-category spread', which is not stated 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 the tool is 'the onboarding entry point' that 'returns category-bucketed example questions' with 'exact tool + argument shape'. It identifies a specific verb (returns) and resource (example questions) and distinguishes itself from siblings by positioning as the 'FIRST' step and referencing meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides guidance on argument usage: 'Call with no arguments for the full spread, or pass topic to focus'.

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

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

Beyond annotations (which mark it as non-destructive and idempotent), the description discloses ownership enforcement and the deactivation behavior, explaining that the row is not deleted and historical events remain accessible via recent_alerts. This adds meaningful authorization and persistence context.

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

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

The description is two concise sentences with no filler. The first sentence delivers the purpose and a key constraint; the second explains the effect. Information is front-loaded and every word 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 annotations covering safety, the description explains the operation, the ownership rule, and the data persistence effect. It doesn't mention return values or error behavior, but given the lack of an output schema and the straightforward nature, it's sufficiently complete. A brief idempotency note could be added, but the annotation covers it.

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

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

The sole parameter id is already fully described in the schema as 'Subscription id (uuid) returned by subscribe,' and the description only references 'by id.' With 100% schema coverage, the description adds no additional semantic value to the parameter.

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

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

The description clearly states the action (cancel), the target (subscription by id), and includes ownership enforcement, which distinguishes it from list_subscriptions and relates to subscribe. It is a specific verb+resource pair with no ambiguity.

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 use when you have a subscription id and want to cancel it, and it clarifies the non-destructive nature. However, it doesn't explicitly state when to use this over alternatives like list_subscriptions or include any when-not guidance, so it lacks explicit exclusions.

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

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

Even with readOnlyHint/openWorldHint/idempotentHint annotations covering the safety profile, the description adds substantial behavioral context: the crucial distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source exists), the mention of verbatim evidence and citations, and the claim that it replaces 4–6 sequential calls. This goes far beyond annotations and materially 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?

Although longer than average, the description is well-structured and every sentence earns its place. It front-loads trigger phrases and core purpose, then flows into routing logic, return values, and critical caller notes. There is no redundancy or filler—dense but efficient.

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

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

Despite lacking an output schema, the description comprehensively covers both processing paths, all six verdicts, citation format, and the error semantics of could_not_verify/unsupported. An agent has enough context to call the tool correctly and interpret its response confidently.

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% parameter coverage with detailed descriptions and examples for both claim and tolerance_pct. The description adds only minor usage context (e.g., 'set 1–2 for hallucination detection'), which does not significantly enhance what the schema provides. Baseline 3 is appropriate.

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

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

The description is highly specific: it states the tool verifies natural-language factual claims against authoritative sources, lists trigger phrases, and describes two distinct routing paths (SEC EDGAR + XBRL for company-financial claims, grounded pipeline for others). It enumerates the exact verdict types returned, making its purpose unmistakable and differentiating it from generic search or research tools.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing logic. However, it does not name alternative sibling tools or provide explicit when-not-to-use scenarios, so it falls 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.