Frankfurter

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, making the tool's safety profile clear. The description adds behavioral details: default model, BYO key for Anthropic, and the return structure (per-model score, confidence, signals, raw_response + combined view). This goes beyond annotations, though cost implications or rate limits are not mentioned—acceptable given the free default.

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, each carrying essential information. It is front-loaded with the action and output, and no unnecessary words are present. Structure is optimal for quick reading.

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 moderate complexity (4 parameters, no output schema), the description is complete. It details the return format (per-model fields plus combined view) and covers all parameters. Annotations provide safety context. Everything an agent needs to invoke correctly is present.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful context: examples for entity, clarifies that models defaults to workers-ai, explains that _apiKey is only needed for anthropic, and notes that context helps disambiguate. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the verb 'probe' and the resource ('LLMs for what they know about a business/brand/product/topic'). This distinguishes it from sibling tools, none of which perform this specific AI visibility audit.

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

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

The description provides clear usage scenarios: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use the default model (free) versus needing an API key for Anthropic. While it doesn't explicitly state when not to use it, the context is sufficient. No alternatives are mentioned, but the tool is quite unique among siblings.

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

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

The description adds meaningful behavioral detail beyond the readOnly/openWorld/idempotent annotations: it reveals dynamic routing, automatic argument filling, and stable pipeworx:// citation URIs in the response. It does not address edge cases like no-results handling, latency, or auth, but for a read-only query tool the disclosed behavior is strong.

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 'PREFER OVER WEB SEARCH' and organized around usage signals, examples, and a closing start-here directive. It earns its length but repeats 'even if web search could answer it' twice, which makes it slightly redundant.

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

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

Without an output schema, the description adequately explains the return shape by mentioning structured answers and stable citation URIs. It also covers routing behavior and broad query categories; the main omission is guidance for choosing between this and the ask_pipeworx_beta/grounded siblings.

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 the six aliases for the single required parameter, so the structured data already fully documents the parameters. The description contributes only natural-language usage examples (e.g., 'current US unemployment rate') rather than new 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 names a specific action ('routes the question to the right tool'), a specific resource domain (5,908 tools across 1,540 verified sources), and an output (structured answer with citation URIs). It clearly differentiates from web search, but it does not explain how it differs from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and gives concrete triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') plus examples. It presents this tool as the default catch-all, but it never states when to prefer the sibling ask_pipeworx variants or deep_research instead.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: candidate routing improvements are enabled live during tests, no candidate is currently active (matching ask_pipeworx exactly), and this is a full working router with no fallback. No contradiction with annotations exists.

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 essential identity: 'Beta version of ask_pipeworx: identical universal router.' Each sentence contributes details about current state, usage, and the tool's working status. The final clarification about fallback is slightly redundant but reinforces a key behavioral point.

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 no-output-schema tool, the description covers identity, current experimental state, usage guidance, and response shape via reference to ask_pipeworx ('same response shape'). It doesn't detail the output structure itself, but since the tool is defined as identical to a known sibling, this reference is sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, and all six parameters are explicitly documented as aliases for question. The description adds no parameter-level meaning beyond telling the agent to use it exactly like ask_pipeworx, so the schema carries the semantic weight. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,908 tools, arguments, and response shape. This makes the tool's function and relationship to its primary sibling unambiguous. It doesn't explicitly distinguish from ask_pipeworx_grounded, but the core purpose is well defined.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains results are compared against the stable router to decide merges, implicitly telling agents to use the stable ask_pipeworx when they don't want the experimental edge. It doesn't enumerate exclusions or other sibling alternatives, but the main selection condition is clear.

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

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

The description goes well beyond the readOnly/idempotent annotations by detailing the internal flow (routing across 5,908 tools, filling arguments, fetching data), the exact success/refusal return shapes, and the full list of refusal reasons. It also discloses the extra LLM call cost, which is relevant behavioral context.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return/refusal contract, when-to-use, and cost trade-off are all packed in a compact block. It is front-loaded with the core value proposition and contains no filler.

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

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

For a complex natural-language lookup tool with no output schema, the description sufficiently covers return values, refusal semantics, use cases, and cost. The explicit refusal_reason list is particularly valuable for agents deciding whether the answer is trustworthy.

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 meaningful context by clarifying that routing and tool selection are automatic and that the question is in natural language ('picks the right tool... fills arguments'), which helps the agent understand its own role in filling the parameters. This goes beyond the schema's basic parameter names.

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

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

The description names a specific, distinctive behavior: 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results, with evidence and explicit refusals. It clearly differentiates itself from the sibling ask_pipeworx by emphasizing groundedness and evidence extraction.

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

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

It explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when to prefer the sibling ask_pipeworx ('casual lookups'), including the trade-off of an extra LLM call. This is direct, actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: fan-out logic, response shapes, resolution contract, parent event extractor, news fallback fields, safety short-circuits, and resolution-rule risk. No contradictions.

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

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

The description is long but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT). It front-loads the core purpose, but some details (e.g., fan-out examples) could be more concise or placed in documentation.

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

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

Given the tool's complexity (3 params, no output schema, rich annotations), the description covers resolution logic, safety mechanisms, edge cases, and response shapes. It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context: market can be slug, URL, or text; depth defaults to thorough; include_raw recommended false with rationale. This goes beyond schema definitions.

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

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

The description uses a specific verb ('Research') and resource ('Polymarket bet'), and details the tool's function: pulling Pipeworx data in one call. It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on research and fan-out.

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 use cases ('should I bet on X', etc.) and provides examples of when to use. However, it lacks explicit guidance on when not to use compared to sibling tools, though the sibling list helps differentiate.

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 non-destructive nature. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and return format with citation URIs. 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 well-structured, starting with trigger phrases, then core action, then type-specific details. It is informative without excessive verbosity, though a bit dense. Every sentence contributes value.

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

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

Given no output schema, the description adequately explains return format (paired data + citation URIs) and sorting behavior. It covers both entity types and edge cases (off-calendar fiscal years), making it complete for a tool with two parameters and moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining what data is pulled for each entity type (company vs drug) and providing examples for the 'values' parameter (tickers/CIKs or drug names), enhancing understanding beyond the schema's enum and 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 explicit trigger phrases like 'Compare X and Y' and clearly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools by noting it replaces 8-15 sequential lookups, making the purpose unmistakable.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It does not explicitly list alternatives or when not to use, but the strong preference directive is sufficient for most cases.

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

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

Annotations already signal read-only, open-world, idempotent, and non-destructive behavior, and the description adds valuable context beyond that: account gating, paid tier requirement for thorough depth, never-invented gaps[], stable pipeworx:// citations, contradiction scanning, semantic excerpting, and expected latency. No annotation contradictions are present.

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

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

The description is long but dense; nearly every sentence contributes distinct information about gating, behavior, output format, alternatives, or timing. It is front-loaded with the most actionable information (account requirement and alternative tool) before explaining the mechanism. Minor redundancy in the depth explanation between description and schema keeps it from 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?

For a complex tool with no output schema, the description covers the output packet shape, citation format, gap handling, contradiction detection, latency expectations, account requirements, and use-case boundaries. An agent has enough context to call the tool correctly and interpret results accurately.

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 meaningful nuance to the depth parameter by explaining facet counts, hops, gap recovery, and contradiction scanning, as well as the paid requirement for thorough. It also reinforces that the question parameter should be natural language and can be broad or multi-part, which is extra 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 identifies a specific verb and resource: conducting grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly distinguishes itself from open-web search and names its closest sibling (ask_pipeworx) with the condition for using that alternative. It also states its intended niche: broad/multi-part questions over structured data.

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

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

The description explicitly says when to use deep_research, when not to use it, and what to use instead: use ask_pipeworx if not signed in, and use ask_pipeworx for a single lookup. It also contrasts this tool with open-web search and positions it for broad or multi-part questions, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full input schemas with curated examples and are ready to call directly, providing useful behavioral context beyond annotations. No contradictions.

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

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

The description is 4-5 sentences, each adding value. It front-loads the core purpose and provides examples, limits, and usage context. Slightly verbose but efficient overall.

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

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

Given no output schema, the description sufficiently describes the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This is complete for an agent to understand what to expect.

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 mentions alias parameters (task, q, description, search) and gives example queries, but these are already covered in the schema. It adds marginal value by explaining that results include schemas, not directly parameter 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses specific verbs and a broad resource, and lists numerous example domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like ask_pipeworx 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 guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies not for direct answers.

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/openWorld/idempotent annotations, the description reveals the fan-out behavior across SEC, XBRL, patents, contracts, FDA, hiring, news, and LEI. It also clarifies important semantics: empty sections are real 'no data', private companies return resolved:false with a notes line, and sources_used/sources_failed are provided. This materially helps the agent interpret results and handle edge cases.

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 examples and a usage directive before enumerating response contents. Every sentence carries meaningful information, and the internal structure keeps the length justified.

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

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

With no output schema, the description carries the full burden of explaining return semantics. It thoroughly describes the returned fields, URI formats, source failure handling, resolved flags, and input resolution behavior. An agent can call this tool and interpret results with minimal ambiguity.

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

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

Schema coverage is 100% and both parameters are already well described. The description reinforces that value can be a ticker, CIK, or company name and that type accepts 'company' or 'ticker' interchangeably, but it does not add significant new meaning beyond the schema.

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

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

The description clearly states its purpose: a full cross-source profile of a US public company in one parallel call. It distinguishes itself from single-domain lookups by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' The examples and resource scope make it easy for an agent to identify what this tool is for.

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

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

The description gives clear usage context: use when the user asks for a holistic company view, and prefer it over chaining multiple single-source lookups. It does not name specific sibling tools like compare_entities or deep_research as explicit alternatives, but the when/when-not guidance is strong enough for selection.

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

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

Annotations already indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true). The description adds that it deletes by key but does not provide additional behavioral context beyond annotations.

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

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

Two sentences, action-oriented, no wasted words. Efficiently communicates the tool's purpose and usage.

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 single parameter, annotations, and no output schema, the description covers the essential purpose and usage. Could mention post-deletion behavior but not necessary.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. The description does not add extra meaning beyond the schema.

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

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

The description clearly states the action (Delete) and the resource (previously stored memory by key). It distinguishes from siblings like 'remember' and 'recall' by specifying 'forget' as deletion.

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 (context stale, task done, clear sensitive data) and mentions pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds behavioral context: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Two sentences plus a use-case list, all relevant and front-loaded. No wasted words; every sentence adds value. Very concise.

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, description explains output is a single text blob. Parameters are fully covered. Annotations provide safety profile. Sufficient for a simple fetch-and-format 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 has 100% description coverage for both parameters (url and max_links). Description adds no new semantics beyond restating defaults already in 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?

Clearly states the tool generates an llms.txt file for a URL, specifying the output format and purpose for AI crawlers. The description distinguishes it from siblings like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

Lists three explicit use cases (client indexing, personal drafting, competitor auditing). However, it does not mention when to avoid this tool or contrast with siblings, leaving some ambiguity.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: data source (ECB), date availability range (1999-01-04 onward), and format example. Output schema handles return values, so no additional explanation needed.

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

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

Three concise sentences with no redundancy. The first sentence states the core purpose immediately, followed by specific constraints and an example. Every sentence adds value.

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

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

Given the tool's simplicity (3 parameters, output schema present, rich annotations), the description covers all necessary contextual details: data source, date range, and usage example. It is fully sufficient for correct invocation and selection.

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

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

Schema coverage is 100% with descriptions for base, date, and symbols. The description provides an example that mirrors the schema but does not add new meaning beyond what the schema already conveys. No parameter semantics are enhanced.

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

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

The description clearly states the tool retrieves exchange rates for a specific historical date, using a specific verb ('Get') and resource ('exchange rates'). It distinguishes from siblings like 'get_latest' and 'get_timeseries' by focusing on a single historical date, and provides an example to reinforce this.

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 historical single-point queries via phrasing 'specific historical date' and the example. While it doesn't explicitly exclude alternatives, the context is clear and the sibling list includes related temporal tools, allowing inference. No exclusions are needed.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint. Description adds context about returning rates relative to base currency and support for many currency pairs.

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 paragraphs, front-loaded with purpose. Every sentence adds value, no wasted words.

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

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

Has output schema, so return values are covered. Description includes usage examples, relation to siblings, and complete guidance for a simple read tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples and explains how to use parameters for conversion (e.g., base and symbols), adding value beyond schema.

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

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

Clearly states it gets the latest FX rates from ECB, with specific verb and resource. Distinguishes from siblings like get_historical and get_timeseries.

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 'PREFER OVER WEB SEARCH' and gives concrete use cases (e.g., 'convert CHF to INR'). References list_currencies for full currency list.

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, covering safety and idempotency. The description adds that it returns daily rates between dates, which is useful context but not critical; the annotations bear most of the burden.

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 with a clear example. No wasted words; front-loaded with purpose and return type.

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

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

Given the tool's simplicity (4 params, annotations present, output schema exists), the description is complete enough. It explains the return (daily rates) and provides an example. No gaps are apparent for typical use.

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 all parameters (date format, defaults, comma-separated symbols). The description provides an example that reinforces usage, but does not add 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?

The description clearly states the tool retrieves exchange rates over a date range for trend analysis, which is a specific verb+resource. It distinguishes from siblings like get_latest by emphasizing the date range aspect, though does not explicitly name alternatives.

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

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

The description implies use for trend analysis over a date range with an example, but does not explicitly state when to avoid this tool or mention alternatives like get_latest for single dates. Usage guidance is implied but not comprehensive.

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 'returns currency codes and full names' but does not provide additional behavioral context beyond annotations.

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

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

The description is a single sentence that front-loads the core action and then provides specifics. No extraneous information.

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

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

For a simple list-all tool with zero parameters and a likely clear output schema, the description adequately describes what the tool does and returns, though it omits potential edge cases or error conditions.

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

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

No parameters exist and schema coverage is complete. The description adds value by specifying that the tool returns currency codes and full names, fulfilling the purpose beyond the schema alone.

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

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

The description clearly states the tool lists all currencies supported by the Frankfurter API, returning codes and names. This distinguishes it from siblings like get_latest or get_timeseries that deal with exchange rates.

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

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

The description implies this is for retrieving a list of available currencies but does not explicitly state when to use it versus alternatives or any prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds marginal value by noting 'active' subscriptions and specifying return fields. No contradictions, but no significant behavioral disclosure beyond annotations.

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

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

Two sentences: first states purpose and outputs, second gives usage guidance. No fluff, content is front-loaded and every sentence serves a clear purpose.

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

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

Despite no output schema, the description compensates by listing all return fields. The single optional parameter is explained. The tool is simple and the description covers all necessary context for an agent to use it correctly.

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

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

Schema coverage is 100% and the only parameter 'include_inactive' is well-documented in the schema. The description does not add any new information about parameters beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the verb ('List') and resource ('the caller's active subscriptions') and lists the return fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more [subscribe] or to find an id to cancel [unsubscribe].' It lacks an explicit alternative name but the context strongly implies the sibling tools.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive, but the description adds critical behavioral context beyond that: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, the claim_token flow for follow-up, and that the team reads digests daily. This fully discloses side effects and constraints.

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

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

The description is long but every sentence carries useful information: purpose, category examples, exclusion for other servers, claim_token usage, rate limit, quota, and digest cadence. However, it could be slightly tightened; for instance, the 'Not sure?' sentence adds clarity but is somewhat redundant with the preceding exclusion. Overall well-structured and front-loaded.

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

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

Given that this tool has no output schema and involves a multi-turn interaction (claim_token), the description is remarkably complete. It explains the input categories, the context object's optional fields, the follow-up mechanism, and operational constraints. All user-facing concerns are addressed without needing to inspect the schema.

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

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

The input schema covers all parameters with 100% description coverage, so the baseline is 3. The description adds extra value beyond the schema by explaining the claim_token workflow explicitly ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which clarifies how to use the parameter in a multi-step interaction. This lifts it above baseline.

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

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

The description opens with a clear statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This uses a specific verb and resource, and the detailed categories (bug, feature, data_gap, praise) make the purpose unambiguous. It also distinguishes itself from sibling research and query tools by clearly stating it is for feedback about Pipeworx tools only.

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 with concrete examples ('wrong/stale data', 'tool you wish existed', 'worked surprisingly well') and explicit when-not-to-use guidance: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance, including a disambiguation rule to avoid misreporting.

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, and destructiveHint=false. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h depending on window), and that it's 'self-aggregating signal'. No contradictions.

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

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

Four sentences, no wasted words. The lead sentence is engaging and informative ('What other AI agents are calling on Pipeworx right now'). Each subsequent sentence adds distinct value: return types, use cases, data provenance, and caching. Perfectly 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?

Given a single well-documented parameter and no output schema, the description covers all necessary aspects: purpose, parameters (with semantics), data provenance, privacy, caching, and practical use cases. It could optionally describe the return format structure, but that is not essential for an agent to use it correctly.

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

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

Schema description coverage is 100% for the single 'window' parameter. The description adds interpretive semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This clarifies the qualitative difference between choices, going beyond the enum list.

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

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

The description clearly states it 'Returns the top tools, top packs, and total call volume' over configurable windows. The verb 'returns' is specific, and the resource (trending data) is precisely described. It distinguishes itself clearly from sibling tools like 'discover_tools' or 'get_historical' by focusing on popularity metrics.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool choice, and checking alignment of use case. While it does not explicitly state when not to use, the practical guidance is strong. It could be improved by contrasting with sibling tools like 'discover_tools' or 'suggest_questions'.

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 readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: semantic anchor threshold (0.30 Jaccard), partition filter (placeholder handling), and fill check logic. 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 lengthy but well-organized with clear sections and front-loaded purpose. Every sentence adds value; however, minor redundancy exists (e.g., 'partition_check' explained twice). Could be slightly tighter.

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 explains the response structure (opportunities[], partition_check, fill risk fields) and caveats (placeholder filtering, Jaccard similarity). It covers all necessary context for correct tool use.

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?

Both parameters have 100% schema description coverage. The description extends meaning by specifying that event accepts full URLs and topic is a seed question, with examples for each. It explains how each parameter changes the tool's behavior (single-event vs. cross-event).

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 via monotonicity violations and partition-sum checks. It specifies three distinct modes (no args, event, topic) with precise behavior for each, fully distinguishing it from sibling tools like polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific markets (recommended), topic for cross-event scanning. Provides a clear 'when not to trade' rule (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing, covering alternatives.

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

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

The description provides extensive behavioral details beyond annotations: caching (1h KV-level), three segments with model specifics, Fed bet exclusion, diagnostics for empty segments, and details on edge and Kelly calculations. 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, lacking structure like bullet points or sections. While every sentence is informative, the formatting hurts readability. It is front-loaded with the purpose but could be more organized.

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

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

Given the tool's complexity (9 parameters, three segments, diagnostics), the description thoroughly covers output structure, tradeable-edge knobs, and caching. Without an output schema, it provides enough information for an agent to understand return values 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 detailed descriptions. The description adds context for parameters like slippage_pp (explains Polymarket fees) and min_partition_leg_kelly (explains why it exists). This additional context justifies a score above baseline 3.

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

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

The description clearly states the verb 'scan', the resource 'top Polymarket markets', and the outcome 'return opportunities where Pipeworx data disagrees with market price'. It is specific and distinguishes from siblings like polymarket_arbitrage by focusing on model-driven edge detection rather than cross-platform arbitrage.

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets', providing clear context for use. However, it does not explicitly exclude alternatives or state when not to use it, relying on sibling names for differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavior: reads from daily snapshots, computes trend and decay, notes gaps when no scan occurred. No contradiction with annotations.

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

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

Description is relatively long but well-structured with clear sections (RESPONSE with sub-items). Front-loaded with main purpose. Could be slightly more concise, but all sentences add value.

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

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

No output schema, but description fully explains return structure (tracked[], expired[], snapshot_dates[]) with details on each field. Covers parameters, limits, and behavioral nuances. Complete for a moderately complex tool.

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

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

Schema covers both parameters with descriptions (100%). Description enriches with defaults (days=14, window='1wk'), ranges (days clamp 2-30), and specific window options (24hr, 1wk, 1mo), adding value beyond schema.

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

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

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, with specific outputs (tracked, expired, snapshot_dates). It distinguishes from sibling tools like polymarket_edges (raw snapshots) and polymarket_arbitrage (arbitrage) by focusing on time-series and trends.

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 answers 'how long has this edge existed and is it shrinking?' and gives a concrete example contrasting a fresh wide edge vs a 3-week-old one. Mentions limits (60-day TTL, daily closes not intraday). Does not explicitly state when not to use or compare to all alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: it walks the order book ladder, returns fill details and slippage, and warns about the risk of partial basket fills converting an arbitrage into an unhedged directional position. 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 lengthy but well-structured with clear section headings (SINGLE-MARKET, BASKET) and bolded key terms. Every sentence adds value, but could be slightly more concise without losing information. Front-loads the core requirement and purpose effectively.

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 enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). This is comprehensive for a complex tool with two modes.

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 has 100% description coverage, so baseline is 3. The description adds significant value by explaining the dual interpretation of size_usd (spend vs target proceeds for single-market; settlement notional for basket) and the auto side logic for basket mode. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs a realizable vs theoretical edge check against live order book depth. It specifies the two modes (single-market and basket) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being the pre-trade validation step.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or any polymarket_edges trade above ~$500. Explains the reasoning (theoretical overround on thin books is not capturable, partial basket fills lead to unhedged directional positions). Provides clear when-to-use guidance.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive, and the description adds substantial behavioral context beyond that: response shape, top_spreads_pp semantics, compatibility_warning and compatibility_codes, skipped_unclassified and low_confidence_pairs, and the explicit warning that spread_pp is gross because Kalshi fees are not modeled. It also clarifies the tricky temporal_alignment null semantics, which is exactly the kind of nuance an agent needs.

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 almost every sentence carries operational weight: modes, response fields, safety codes, skipped-leg counters, and fee caveats. It is front-loaded with the core definition and then layers detail logically, though it is dense enough that an agent must parse carefully and a couple of warnings are repeated for emphasis.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it delivers: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, and temporal_alignment semantics. It also covers edge cases like unknown metric_type/match_subtype, cross-type and cross-subtype skipping, and the fees_note standing disclosure, making it complete for a complex cross-venue comparison tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the parameter descriptions by explaining what topic actually does (10 pre-mapped shortcuts that auto-fetch matching events), how explicit ticker/slug overrides interact with the topic mode, and that both modes use the identical token-overlap matcher. This helps an agent choose parameter combinations confidently.

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

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

The opening sentence states a specific operation—computing the cross-venue spread between Kalshi and Polymarket for the same resolving question—and clearly frames the tool's unique value. It distinguishes itself from sibling tools by emphasizing Kalshi/Polymarket pairings and by calling out when bet shapes are equivalent versus when they are not, so an agent can tell it apart from descriptors like polymarket_arbitrage.

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

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

The description gives explicit usage context: two modes (topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug), when each applies, and that both run the same matcher. It also warns that pre-mapped topics are often not tradeable and that real cross-venue spreads are rarer than the shortcut list suggests, giving the agent strong expectations about when the result is meaningful. It does not name or contrast sibling tools explicitly, so it falls just 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 and idempotentHint=true. Description adds that it retrieves previously saved values, lists all keys when omitted, and is scoped to an identifier, providing useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose, then usage and scope. No extraneous information.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, and pairing. Could mention return format but 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 description adds minimal extra beyond the schema's 'omit to list all keys'. 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 clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' and resource 'value saved via remember'. It distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and scoping, but lacks explicit alternatives or when-not to use. The context is clear enough for an 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?

Annotations indicate read-only and idempotent, but the description reveals mark_read can flag events as read (a side effect). It also details return fields (source, citation_uri, payload). This adds behavioral context beyond 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 concise, front-loaded with the main action, and every sentence adds value—purpose, return fields, filtering, side effect, and alternative access—with no fluff.

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

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

For a read-only list tool, the description covers return structure, filtering, and polling suitability. No output schema exists, but the description explains event components. It is complete enough for effective use.

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 parameter descriptions. The description briefly reinforces filtering by type and since, but does not add substantial 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 states the tool 'Pull fired events from your subscription feed' with specifics on returned data (source, citation_uri, payload) and filtering options, clearly distinguishing it as an alert retrieval tool.

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

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

The description mentions 'Polls work fine' and provides an alternative REST endpoint, offering some usage context. However, it lacks explicit guidance on when to use this tool versus siblings like 'get_latest' or 'list_subscriptions'.

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. Description adds valuable behavioral context: fans out to multiple sources with fallback (GDELT→GNews), soft-fails on USPTO, returns structured changes with citation URIs. 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?

Single paragraph front-loaded with natural language examples. Every sentence adds necessary context about sources, fallback, parameter formats, return structure, and sibling differentiation. No wasted words.

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

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

Despite no output schema, the description fully explains the return format (structured changes grouped by source, total_changes count, citation URIs). It covers source behavior, fallback logic, parameter details, and cross-tool guidance. An agent has sufficient context to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: explains `since` format with examples and recommended values, clarifies `value` accepts ticker or CIK, and notes `type` is limited to 'company'. This enriches the semantic understanding.

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

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

The description clearly states the tool provides a change feed for a company (SEC filings, news, patents) in a given time window, with example queries. It distinguishes from sibling 'entity_profile' by noting when to use that instead.

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

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

Explicitly says when to use this tool ('what's new with X' queries) vs entity_profile (static profile). Provides examples of query phrasing and explains `since` format options (ISO date or relative shorthand) with specific recommendations like '30d'.

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?

Describes persistence behavior (authenticated vs anonymous), scoping by identifier, and pairs with recall/forget. Annotations confirm 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?

Four concise sentences, each serving a purpose: purpose, usage, scope/persistence, tool pairing. No wasted words.

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

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

For a two-parameter tool with no output schema, description fully explains storage behavior, scope, and lifecycle. Sufficient for correct agent invocation.

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

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

Input schema covers both parameters with descriptions. Description adds valuable examples of keys and values, enhancing understanding beyond schema.

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

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

Clearly states the tool saves data for reuse across conversations and sessions, with specific verb 'save' and resource 'data'. Distinguishes from siblings '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', with concrete examples. Names sibling tools for retrieval and deletion.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral traits: cross-source identity spine, non-equity instrument support, candidate ambiguity behavior, explicit unresolved field, graceful degradation when GLEIF/OpenFIGI unavailable, and internal cascading lookups. This richly exceeds annotation coverage.

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 and dense, but nearly every sentence earns its place by documenting edge cases, supported types, or failure behavior. It is front-loaded with purpose and alternatives. Some redundancy and heavy use of parentheticals make it slightly harder to parse than necessary, but it is not padded.

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 comprehensively covers input formats, supported types, output identifiers, candidate behavior, unresolved results, source attribution, and failure degradation. For a complex resolution tool with multiple cascading lookups, the agent has enough context to call it correctly and interpret ambiguous 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?

Although schema coverage is 100%, the description adds crucial meaning beyond the schema: concrete input examples for ticker, CIK, ISIN, generic drug names; the warning to pass the entity name only; and the explanation that trailing security-class words break FIGI matching. This materially improves parameter understanding.

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

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

The description opens with concrete user queries and states the core function: resolve a user-spoken NAME to canonical/official identifiers. It clearly distinguishes this tool from siblings by framing it as the precursor to other tools that require IDs, and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID,' and explains supported entity types. It does not name sibling tools or state explicit when-not-to-use conditions, but the broad 'use first' directive and detailed type-specific semantics provide clear context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: it probes each entity with ai_visibility_check, returns a ranked list with score/confidence/signal density, and treats the first entity as a subject. No contradictions.

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

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

The description is three concise sentences, front-loaded with the primary action and followed by a use case and return details. 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?

Despite no output schema, the description explains the output format (ranked list with score, confidence, signal density). All four parameters are described adequately, and the tool's moderately complex logic (comparison, ranking) is clearly outlined. The description fully equips an agent to use the tool correctly.

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

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

With 100% schema coverage, the description still adds value: it explains that the first entity in the array is treated as the 'subject' for narrative, that models defaults to just workers-ai, and that context disambiguates common names. This enriches understanding 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking results. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive audit use case.

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

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

The description provides a clear when-to-use scenario ('competitive AI-marketing audits') and implicitly suggests the alternative ai_visibility_check for single-entity queries. However, it does not explicitly state when not to use this tool or list other alternatives like compare_entities.

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

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

Annotations already show readOnlyHint, idempotentHint, destructiveHint, so tool is safe. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradictions.

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

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

Description is detailed but front-loaded with purpose. Each sentence adds value. The list of return fields is verbose but necessary given no output schema. Could be slightly trimmed but overall concise for complexity.

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

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

Given no output schema, description provides comprehensive return fields. Covers NPM-only scope, partial failures, timing, and graceful degradation. All relevant context is present.

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

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

Schema covers 100% of parameters with descriptions. The description adds extra meaning: scoped packages accepted, version defaults to latest. This adds value beyond schema.

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

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

The description clearly states it's a composite check for adding an npm package, combining deps.dev and bundlephobia data. It uses specific verbs and resources, and distinguishes from sibling tools like deep_research or 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 when to use it ('when agent asks is X safe / popular / small') and notes ecosystem limitations ('NPM ecosystem only in v1'). It could be more explicit about alternatives within siblings, but the context is clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), it adds embedding details (BGE-base-en, cosine similarity over 500-char windows), character cap (200K with truncation flag), and output content (offsets, similarity scores). 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?

Concise and front-loaded with purpose; technical details follow. Every sentence adds value, though slightly more concise possible.

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 explains return format (passages with offsets and similarity). Covers all necessary context: use case, how it works, limitations (character cap), and integration hints.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description adds usage context (e.g., query examples, default limit) but does not introduce new parameter meaning beyond schema.

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

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

The description uses specific verb ('semantic search') and resource ('inside a fetched record'), and distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing.

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 (record too big for prompt, save context), when not to (use ask_pipeworx_grounded for grounding), and provides query examples.

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

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

The description contradicts the idempotentHint annotation by implying a new subscription is created each time, suggesting non-idempotent behavior. This is a direct contradiction, so the score is 1 per the scoring rule for annotation 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 well-structured and front-loaded with core purpose and return value. It is relatively long but each sentence provides necessary detail without redundancy. A slight trim could be possible, but it remains efficient.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description comprehensively covers return value, prerequisites, type examples, delivery channel mechanics, and edge cases like webhook auto-disable. It leaves little ambiguity for agent usage.

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 substantial value beyond schema by providing concrete JSON examples for each type, explaining delivery constraints (e.g., SMS cap, webhook auto-disable), and clarifying required fields like sponsor or condition for clinical_trial.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by detailing subscription types and delivery channels.

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

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

The description specifies prerequisites (Pipeworx OAuth account) and provides explicit guidance on supported types and delivery methods. It lacks explicit when-not-to-use or alternative comparisons, but the context is clear enough for agent decision-making.

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, destructiveHint, and the description adds valuable behavioral context: it is the onboarding entry point that returns live catalog examples with exact tool shapes. No contradictions.

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

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

The description is thorough and well-structured, starting with aliases and examples, then detailing the return format and usage. Slightly verbose but all sentences add value; could be more concise without losing clarity.

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

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

Given no output schema, the description fully explains the return value (category-bucketed example questions with tools+arguments). It covers all aspects: topics, call patterns, and the meta-tools. Complete for a tool with one optional parameter and rich annotations.

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

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

Schema coverage is 100% with one optional parameter. The description adds significant meaning by listing possible topic values (e.g., 'finance', 'pharma'), explaining that omitting topic gives full spread, and providing context for usage.

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 returns category-bucketed example questions with tool+argument shapes, and positions it as the onboarding entry point when the agent doesn't know Pipeworx's capabilities. It clearly distinguishes from siblings by its specific purpose and usage context.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It explains when to use it (onboarding, getting ideas) and mentions alternatives like ask_pipeworx, entity_profile, compare_entities. Also specifies calling with/without arguments.

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. It reveals that the operation is a deactivation (not deletion) and that historical events remain available via 'recent_alerts', which is critical behavioral context. The annotations already indicate non-destructive and idempotent, and the description aligns 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?

Two sentences, no fluff. The verb and resource are front-loaded, and every sentence adds essential information (ownership, deactivation vs deletion, historical data).

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 covers the core purpose, behavioral effect, ownership, and reference to historical availability. For a simple unsubscription tool with one parameter, it is mostly complete. Minor gap: it does not mention error handling (e.g., invalid id or not owned) or prerequisites like authentication.

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 parameter 'id' is well-described in the schema as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no additional constraint or formatting 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?

The description uses the strong verb 'Cancel' and specifies the resource 'subscription by id', clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also clarifies the effect (deactivation vs deletion) and ownership enforcement.

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

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

The description states ownership enforcement, implying the user must own the subscription to cancel. It references 'recent_alerts' for historical data, providing context. However, it does not explicitly state when not to use the tool or compare to alternatives like 'subscribe' (for creating) or other cancellation methods.

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 (readOnlyHint, idempotentHint, openWorldHint, destructiveHint) are complemented by rich behavioral disclosure: exact verdict set, distinction between 'could_not_verify' (check failed, not evidence) and 'unsupported' (no source coverage), inclusion of 'verification_error{stage,detail}', and the 'pipeworx://' citation format. No contradiction with annotations exists.

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 detailed and front-loaded, starting with natural-language trigger phrases. While somewhat long, every sentence adds value—the two verification paths, verdict semantics, and error handling are all essential. It avoids redundancy, but the length and inclusion of 'Replaces 4–6 sequential calls' could be trimmed without losing core information.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error semantics) and lack of an output schema, the description fully compensates by enumerating the exact verdict states, distinguishing error conditions, and promoting safe usage (could_not_verify must not be presented as evidence). It supplies all needed context for correct invocation and interpretation of 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?

Input schema already provides 100% coverage of both parameters with detailed descriptions. The tool description adds extra semantic value by explaining tolerance_pct's role in hallucination detection ('set 1–2') and how default tolerance is capped at 5, which goes beyond the schema's generic 'Max percent deviation' phrase.

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

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

The description clearly identifies the tool as natural-language claim verification with explicit verb phrases ('fact check', 'verify the claim') and a specific resource (authoritative sources). It distinguishes itself from sibling tools by describing the two distinct verification pipelines (SEC EDGAR for financial claims, grounded pipeline for all others), making its unique role clear.

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

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

Provides explicit usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the decision path between company-financial claims and other factual claims, and notes that it replaces 4–6 sequential calls, implying efficiency benefits. No exclusions are needed because the tool covers both structured and grounded domains.

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