Openiban

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds substantial context: default model (Workers AI Llama-3.3-70b), cost implications (BYO key, pays Anthropic directly), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond the annotations to set accurate expectations.

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

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

Two sentences, front-loaded with the core action, followed by necessary details and use cases. Every clause earns its place—no filler or redundant statements.

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 4-parameter tool with no output schema, the description covers the essential needed: what it does, how to use it, what to expect in return, and common use cases. The annotations fill in the safety profile, making this complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by clarifying the default model behavior ('Default model is Workers AI Llama-3.3-70b (free)') and the API key implication ('BYO key — you pay Anthropic directly'), which supplements the schema descriptions without repetition.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools such as scan_competitor_ai_presence by focusing on general visibility scoring per model rather than competitor-specific scanning.

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 clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly contrast with alternative tools or provide when-not-to-use conditions, but it gives sufficient context for when this tool is appropriate.

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

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

With annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable context: it routes to the correct tool, fills arguments, returns stable citation URIs, works on every tier, and is fast. It doesn't contradict annotations and gives insight into internal behavior.

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

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

The description is long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH', 'START HERE'). Every section serves a purpose: use cases, examples, alternatives, and tier guidance. It is structured with clear imperative statements.

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 (5,462 tools, 1419 sources) and no output schema, the description fully addresses purpose, usage, examples, alternatives, and behavior. It even mentions citation URIs and performance characteristics. No critical information is missing.

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

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

Schema coverage is 100% with the 'question' parameter and aliases fully documented. The description adds a general sense that the input is a natural language question but doesn't provide syntax or formatting details beyond that. Baseline of 3 is appropriate as the schema does the heavy lifting.

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: 'Routes the question to the right one of 5,462 tools across 1419 verified sources' and returns structured answers with citations. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives. Includes examples and trigger phrases like 'what is', 'look up', 'get the latest', making it clear when to use.

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

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

Annotations already mark it read-only and idempotent; the description adds behavioral context: it's a live experimental router that switches candidate improvements on/off, currently matches stable, and 'Falls back to nothing' confirming it's fully functional. Does not contradict annotations.

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

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

Four sentences, each serving a purpose: identity, current state, usage, and clarification. Efficient for the tool's complexity, though slightly longer than necessary for a simple tool.

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

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

Given the tool's complexity (universal router with dynamic candidates), the description explains what it is, its current equivalence to stable, how to use it, and that it's not a fallback stub. It references 'same response shape' to cover return values, which is sufficient for an agent familiar with ask_pipeworx.

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

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

Schema covers 100% of parameters with descriptions for question and all five aliases. The description adds no information about parameter usage beyond what the schema already provides, so baseline 3 applies.

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

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

Clearly identifies as a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. Distinguishes itself from the stable sibling by marketing itself as the experimental edge and explicitly stating it's a full working router.

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.' Also clarifies the current state (no active candidate) and that results are compared against stable. However, it doesn't explicitly state when not to use it (e.g., for guaranteed stability), so exclusions are missing.

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 far beyond the annotations by disclosing the refusal behavior with specific reasons (not_in_source, no_tool_match, etc.), the output structure, and the cost tradeoff (one extra LLM call). It also clarifies the grounding principle ('using ONLY what the tool result contains'). No contradictions with the readOnlyHint, openWorldHint, or idempotentHint 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 packed with valuable information in a compact format. It front-loads the core purpose, then explains the routing mechanism, output/refusal structure, usage guidance, and cost tradeoff. No wasted words; every sentence earns its place.

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

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

Despite having no output schema, the description explicitly details the success and refusal return structures. It covers when to use, behavior, cost, and limitations. Given the tool's complexity and the presence of rich annotations, the description fully compensates for any missing structured output details.

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

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

Schema description coverage is 100% (all six parameters are aliases for 'question' and are described). The description does not add parameter-specific semantics beyond stating the question is in natural language, which the schema already covers. Baseline score of 3 is appropriate since the schema handles parameter clarity completely.

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 'hallucination-resistant answer mode for high-stakes reads' and explains it 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes itself from sibling 'ask_pipeworx' by emphasizing grounding and evidence, making the specific functionality 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and lists example use cases (financial verdicts, legal claims, medical lookups). It also gives an exclusion: 'prefer ask_pipeworx for casual lookups,' noting the extra LLM call cost. This is ideal alternative guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses many behavioral traits: low-confidence short-circuit with status:'low_confidence_match', market_closed_or_inactive handling, wide-spread market tradeability notes, parent_event extractor behavior, news fallback with _fallback_attempted fields, and resolution-rule risk parsing (cancellation_rule). These details give agents a strong sense of edge cases and safety mechanisms, which annotations alone do not provide.

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

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

The description is long but extremely well-structured, using uppercase headers to delineate sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the core purpose. While it is verbose, each section adds necessary detail for a complex tool, and the structure makes it navigable. It earns its length, though it could be tightened slightly without losing 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?

The description is exceptionally complete for a tool with no output schema. It explains response shapes (result.market, result.analysis, result.evidence), resolver matching confidence and suggestions, parent_event extraction, news field fallback mechanics, safety short-circuits, and resolution-rule risks. It covers edge cases (de-indexed markets, wide spreads, cancellation rules) that are critical for correct usage. No output schema is needed because the description effectively documents the return structure.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already thoroughly documents each parameter (market accepted formats, depth quick/thorough, include_raw size trade-offs). The description adds high-level context about fan-out and response shapes but does not materially enhance parameter-level semantics beyond what the schema already provides. Thus a score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input forms (slug, URL, question text) and the core workflow (resolve, classify, fan out, return). This distinguishes it from sibling tools like polymarket_arbitrage or validate_claim by focusing on research and evidence gathering rather than trading or verification.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifier categories and fan-out examples that imply appropriate contexts. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare safe, read-only, idempotent behavior, but the description adds crucial context: off-calendar fiscal year handling, specific data sources (SEC EDGAR/XBRL, FAERS), sorting behavior, and citation URIs in the response. This significantly enriches what the agent knows about the tool's behavior beyond structured fields.

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

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

The description is dense and highly informative, mixing trigger phrases, usage policy, data source notes, and result behavior. It is front-loaded with the core purpose and each sentence earns its place, though slightly longer than strictly necessary. Still, it remains efficiently structured.

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

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

Given the tool's complexity and absence of an output schema, the description fully captures input limits, per-type data pulls, sorting behavior, and return characteristics (paired data + citation URIs). It also addresses edge cases like off-calendar fiscal years, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions already for both parameters, but the description goes further by explaining what each type retrieves (e.g., company: LATEST 10-K revenue, net income; drug: FAERS counts, FDA approvals) and providing concrete examples. This fully compensates for any potential ambiguity and adds real semantic value.

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

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

The description explicitly states the verb 'compare' with a defined resource scope ('2–5 companies or drugs in ONE parallel call') and differentiates itself from sequential single-pack lookups. It clearly maps trigger phrases like 'X vs Y' and 'which is bigger' to the tool's purpose, leaving no ambiguity.

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

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

The description gives an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also specifies the number of entities allowed (2–5), type-specific data sources, and even explains how results are sorted, providing clear guidance on when and how to use the tool versus alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds no contradiction — it explicitly says findings are 'never invented', contradictions are flagged, and large records are semantically excerpted. It also discloses behavioral traits beyond annotations: the account/paywall requirement, the 15-60s (up to ~90s for thorough) latency, the gap-recovery hop behavior, the citation_uri guarantee ('always fetchable'), and the `hop` field on findings. This is comprehensive behavioral disclosure far beyond what the annotations provide.

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

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

The description is information-dense but long, running seven sentences and packing in many details (signup URL, paid plan, 1419 sources, 5,462 tools, 15-60s latency, hop field, citation_uri semantics, semantic excerpting, contradictions[]). While every sentence earns its place to some degree, the density makes it harder to scan quickly, and the signup/link detail at the front delays the core purpose statement. The lead sentence already covers purpose plus the exclusion framing, but several clauses (e.g., 'never invented', 'fetched_at') could have been trimmed or appended. It is not the minimal viable description, but it is effectively structured with the most important contrasts early.

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 parameters, one enum, no output schema, rich behavioral requirements), the description covers everything needed for correct invocation: authentication requirements, alternatives, latency, return structure, gap behavior, contradiction flagging, citation fetchability, and semantic excerpting. There is no output schema to lean on, and the description compensates fully by explaining what a findings packet contains. The only minor gap is not explicitly describing the exact JSON shape of the findings packet, but the description's enumeration (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop) covers the semantic content.

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

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

Schema coverage is 100% for both parameters, providing a baseline of 3. The description adds direct parameter semantics: it ties depth levels to behavior ('thorough' = paid plan, re-angles gaps, chases leads; 'standard' = default, adds gap recovery + contradictions scan; 'quick' = single hop) and explains that the question can be broad/multi-part because decomposition is the point. It even references the question parameter's value semantics by giving examples. It doesn't fully document every aspect of the depth enum output differences, but the schema already enumerates the values and the description substantially enriches their meaning.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It clearly distinguishes from the sibling tools by explicitly contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx') and by stating 'this is NOT open-web search'. The resource boundary is exceptionally clear: it operates only on structured data sources and will return gaps for topics outside them.

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 when-to-use: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also names alternatives with directional guidance: 'use ask_pipeworx instead' for non-signed-in users, and explicitly says to prefer ask_pipeworx for breaking news / 'what's the world saying about X' topics, explaining why. Depth-tier guidance is also provided, clarifying when each depth level is appropriate through the hop mechanics.

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

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

Annotations already disclose read-only, idempotent, non-destructive. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly, eliminating second lookups. This is useful behavioral context beyond annotations. However, it doesn't mention any limitations or rate limits, and with annotations covering safety, a 4 is appropriate.

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

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

Description is somewhat long due to domain list, but every section has purpose: purpose statement, usage triggers, return behavior, and positioning. It's front-loaded with the core verb and resource. The domain list could be trimmed but is informative.

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

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

For a discovery tool with no output schema, the description fully explains the return value (top-N tools with names, descriptions, input schemas, curated examples) and its role as a first-call option. It covers both request and response semantics sufficiently.

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

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

Schema description coverage is 100% with clear parameter descriptions and examples. The description mentions 'query' accepts natural language and 'limit' default/max, which is already in schema. It does add the alias information but that's also in schema. Baseline 3 is correct.

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 'Find tools by describing the data or task' and explicitly positions it as a discovery tool for browsing/searching across many domains, distinguishing it from sibling tools that perform specific data tasks. It also frames it as a first-call meta-tool, setting it apart.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It doesn't explicitly name alternatives or when-not-to-use, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds behavior beyond annotations: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' in a single parallel call, discloses a potential service sunset with 'soft-fails until reactivated,' and describes the fallback chain 'GDELT→GNews fallback.' This rich behavioral context goes well beyond the annotation metadata.

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

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

The description is long but every clause contributes useful information. It front-loads usage examples, then systematically describes the return structure and parameter constraints. It is dense yet organized, though the initial series of quoted phrases could be trimmed without losing core meaning.

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

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

With no output schema, the description carries responsibility for explaining return values. It enumerates the exact fields returned (cik, company_name, recent_filings, fundamentals, patents, news, LEI), including formatting details like 'pipeworx://edgar/company/{cik}/filings/{accession} URIs' and sorting ('sorted period_end DESC'). It also covers failure modes ('soft-fails') and parameter restrictions, making the tool fully understandable without an output schema.

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

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

Schema description coverage is 100%, with both parameters fully described. The description essentially repeats the schema's parameter guidance, adding only illustrative examples ('AAPL', '0000320193'). No new semantics beyond the schema are introduced, so the baseline of 3 applies.

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

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

The description begins with concrete query examples, then defines the tool as producing a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes the holistic scope from single-source lookups and lists the exact data sources and fields returned. This is more than a generic verb+resource; it sets precise expectations.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This covers both positive and negative usage scenarios.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description confirms by saying 'Delete'. It adds context about clearing sensitive data and that it targets previously stored memories, which is useful beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action, and includes usage guidance without waste.

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

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

For a one-parameter tool with comprehensive annotations and schema, the description covers purpose, usage, and data context. It doesn't discuss error handling, but that's not essential given the tool's simplicity.

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

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

The schema already describes key as 'Memory key to delete' (100% coverage). The description reinforces by mentioning 'by key' and 'previously stored memory' but does not add substantial new detail.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource. It clearly differentiates from sibling tools like remember and recall by specifying the deletion action.

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

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

It explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with remember and recall. It lacks explicit when-not guidance but provides clear contexts.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context about the workflow (fetches page, extracts title/description/links) and the exact output format (standard llms.txt markdown, single text blob). It does not discuss edge cases or rate limits, but the added detail is sufficient.

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

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

The description is compact, front-loaded with the primary action, and uses a clear list of use cases. Every sentence adds value, and the structure makes it easy to scan.

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

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

Given the tool's simplicity, strong annotations, and full schema coverage, the description covers the what, why, and output format. It explicitly states the return value ('single text blob ready to drop at site-root/llms.txt'), which is crucial since no output schema exists.

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

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

Schema coverage is 100% for both parameters (url and max_links). The description does not add new parameter-level detail; it only reinforces that url is the target site. This aligns with the baseline of 3 when the schema carries the full burden.

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

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

The description states a clear action ('Generate a production-ready llms.txt file') with a specific resource and context ('for any URL'). It also explains the process (fetch, extract, emit) and output format, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit 'Useful for' scenarios (client sites, own projects, auditing competitors). It lacks explicit alternatives or when-not-to-use instructions, but the use cases are clear enough for most situations.

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?

Given that annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful context by specifying the return fields and the 'caller's active' scope. It also notes the default behavior of excluding inactive subscriptions, which aligns with the include_inactive parameter but is not redundant with the schema or annotations.

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

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

The description is two concise sentences, front-loaded with the main action and then providing return fields and usage guidance. Every sentence contributes value without redundancy, making it exceptionally 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?

The tool is simple (one optional parameter) and the annotations cover safety. The description explains the return fields (compensating for lack of an output schema), the scope, and when to use the tool. It is fully 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?

The input schema has 100% coverage for the single optional parameter (include_inactive), with a description explaining it. The tool description does not add extra detail about the parameter beyond mentioning 'active subscriptions' in the purpose, which indirectly aligns with the default false. Since the schema already documents the parameter adequately, a baseline score of 3 is appropriate.

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

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

The description opens with the specific action 'List the caller's active subscriptions', clearly identifying the resource (subscriptions) and scope (caller's). It further lists the return fields, which distinguishes it from sibling tools like subscribe and unsubscribe that perform different actions.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly differentiates from subscribe/unsubscribe tools but does not explicitly name alternatives or state when not to use the tool, so it falls short of a full 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 provide no positive safety hints, so the description carries the burden and discloses useful behavior: rate-limited to 5 per identifier per day, free/unquota'd, and read as daily digests that affect roadmap. It also clarifies scope to only this connection's tools. It does not contradict annotations.

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

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

The description is relatively long but front-loads purpose and then layers use-cases, exclusions, content guidance, and constraints in a logical order. Each sentence adds a distinct piece of value (scope, rate limit, quota) with no filler or redundancy.

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

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

For a side-effecting feedback tool with no output schema and no meaningful annotations, the description covers the key decision factors: when to use, when not to use, how to phrase feedback, scope, and operational constraints. It is complete enough for an agent to select and invoke correctly without further clarification.

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

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

The schema already fully describes all 3 parameters (100% coverage), so baseline is 3. The description adds meaningful use-level semantics by equating 'broken/missing' to categories and instructing users to be specific and avoid pasting user prompts, which helps message content quality. This goes slightly beyond the schema's enum labels.

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

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

The description opens with a specific action ('Tell the Pipeworx team') and scopes it to reporting broken/missing functionality, clearly identifying this as the feedback tool among siblings. It distinguishes itself from inquiry/other tools by naming concrete use cases (bug, feature, praise).

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 'Use when' clauses map trigger scenarios to feedback types, and it provides a clear exclusion: do NOT file feedback for tools from other MCP servers, directing users to file with that server instead. It also gives practical guidance on what to include (Pipeworx tools/packs, not end-user prompts).

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds valuable context beyond those: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy guarantees, result format, and caching behavior.

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

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

The description is moderately sized and well-structured: a hook sentence, a clear output statement, a numbered list of use cases, and a concise note on privacy/caching. It earns its length, though some phrasing ('Self-aggregating signal') is slightly redundant with the analytics-engine note, preventing 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 simple tool with one optional parameter and no output schema, the description covers all necessary aspects: what it returns, the window choices, use cases, data source, privacy, and caching. Combined with thorough annotations, this is fully complete for an agent to decide when to invoke.

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

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

The input schema provides 100% coverage for the window parameter, including its enum and description of behavioral differences ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description only repeats the window values without adding new meaning, so it does not elevate above the baseline.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It also opens with a distinctive value proposition ('What other AI agents are calling on Pipeworx right now') that differentiates it from sibling tools like discover_tools or recent_alerts.

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 use cases ('Useful for: discovering what data sources are hot... confirming a popular tool is the canonical choice... seeing whether your use case aligns'), which gives clear context on when to use it. However, it does not mention when not to use it or compare it to alternative tools, so it falls short of a 5.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description goes far beyond annotations by disclosing threshold behavior (>3pp signals), semantic anchoring (Jaccard ≥ 0.30), partition filtering (placeholder >20% returns null), and fill-check mechanics against CLOB depth. It even warns that `realizable_edge_pp ≤ 0` means the edge is not tradable, preventing misuse.

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

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

The description is long but every section earns its place. It opens with the core purpose, then systematically explains modes, filters, semantic rules, and output format using labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). This structural clarity justifies the length for a complex tool.

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

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

With no output schema, the description fully compensates by specifying the exact response fields (`opportunities[]`, `partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}`) and how to interpret results. It covers all input modes, internal logic, edge cases, and even directs to `polymarket_fill_risk` for additional sizing needs, making it complete for an agent to invoke and act on.

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

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

While the schema covers both parameters at 100% with descriptions, the tool description adds substantial operational meaning: `event` mode walks child markets and checks date/threshold-axis ordering plus partition_sum; `topic` mode searches related events and flattens the union. It provides concrete slug and seed examples, and explains how responses differ per mode, making parameter semantics richer than 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly stating the action, resource, and method. It then breaks down three invocation modes (`trending_scan`, `event`, `topic`) with distinct use cases, effectively differentiating itself from generic market tools and even sibling tools like `polymarket_edges`.

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

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

The description explicitly says 'Call with NO args for a trending_scan... pass event for... or topic for...' and provides concrete examples for each mode. It recommends `event` for a specific market and explains when cross-event scanning is beneficial. It also points to `polymarket_fill_risk` for custom sizing. However, it does not explicitly state when NOT to use this tool in favor of other sibling tools like `polymarket_edges` or `polymarket_edge_tracker`, so it's not a fully 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?

Despite annotations already declaring readOnly/idempotent/non-destructive, the description adds extensive behavioral detail: caching at the KV level for 1 hour keyed on knobs, the response segmentation (by_segment), diagnostics for empty segments, and the 24h-move warning. It also discloses how edge is computed net of slippage and why partition arbs return kelly_fraction_half=0 at parent level. 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 densely packed and well-structured with capitalized headers, but it is quite long. It includes highly specific details like per-sport alpha values and placeholder slug patterns that could arguably be truncated; while every sentence carries information, the sheer length makes it less concise than ideal. It is front-loaded with purpose, but overall it is verbose.

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 takes full responsibility for explaining the return structure. It meticulously describes by_segment, fed_candidates/fed_note, _diagnostics, and the fields each opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also explains filter behavior and edge cases, making the tool fully understandable for an agent without external documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by grouping knobs under 'TRADEABLE-EDGE KNOBS' and explaining why min_kelly doesn't filter partition opportunities, and how min_partition_leg_kelly applies to per-leg Kelly instead. This explains the 'why' behind parameters, which is valuable.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the purpose ('what should I bet on today') and differentiates from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-model disagreement discovery and segmenting outputs. This is a distinctive, actionable purpose.

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

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

The description explicitly frames the tool for opportunity discovery ('Built for "what should I bet on today"') and includes an important exclusion (Fed bets are surfaced but excluded from ranking). However, it does not explicitly name alternative tools or state when not to use this tool. Clear context, but lacks explicit alternative 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?

Despite annotations already indicating read-only and idempotent behavior, the description adds substantial behavioral detail: it explains the three response sections (tracked, expired, snapshot_dates), defines the fields within them, and explicitly discloses data limitations such as the 60-day TTL, daily close granularity, and gaps in snapshot coverage. This goes well beyond the annotations and is highly transparent.

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 with clear sections: intro, Args, RESPONSE, and LIMITS. It front-loads the core purpose and packs in useful details without wasted words. Every sentence contributes meaningful information, making the length justified for the complexity of the tool.

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

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

With no output schema, the description takes full responsibility for explaining the return structure. It thoroughly describes tracked[], expired[], and snapshot_dates[] including key fields and their meaning (e.g., trend, decay_pp_per_day, lifespan_days). It also covers important limitations and operational context, making it complete for a telemetry tool with no output schema.

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

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

Schema description coverage is 100% and the schema already provides defaults and constraints for both parameters. The description adds a bit of extra semantic framing ('snapshot family', 'lookback') but does not materially improve on the schema's own descriptions. Since the schema handles the heavy lifting, the baseline of 3 is appropriate.

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

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

The description opens with a specific and informative purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly identifies the resource (edge snapshots) and the specific analytical function (persistence/decay), directly answering the question 'how long has this edge existed and is it shrinking?' This distinguishes it strongly from sibling tools like polymarket_edges, which likely provide current edge values.

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 strong contextual guidance by contrasting a 'fresh wide edge' with a '3-week-old wide edge' and noting they are different trades. It implies the tool is for understanding edge duration and decay, not just current edge strength. It mentions that snapshots are written when polymarket_edges runs, but it does not explicitly name alternative tools or state when not to use this tool, 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, idempotentHint=true, and destructiveHint=false, and the description aligns with them. The description goes well beyond annotations by detailing the ladder-walking behavior, the verdict outputs (clean|degraded|cannot_fill), and the basket-mode settlement semantics. It also warns about the dominant loss mode, adding decision-relevant context without contradicting any annotation.

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

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

The description is dense but efficient, front-loading the purpose and requirements. However, it is a long paragraph with heavy inline formatting (parentheses, lists) that could be broken into bullet points for easier parsing. Every sentence earns its place, but the wall-of-text structure slightly harms scannability.

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

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

With no output schema, the description fully enumerates the expected return values for both single-market and basket modes, including specific field names and verdict values. It also covers parameter defaults, modes, and the exact trigger conditions for using the tool. It is complete for a complex two-mode 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?

Although schema coverage is 100%, the description adds meaningful interpretations: it explains the mutually exclusive market/event modes, clarifies side choices per mode (e.g., sell_yes = capture overround), and redefines size_usd as settlement notional in basket mode. This is significant added meaning beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and enumerates distinct outputs for each. It clearly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by framing this as 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?

The description explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides behavioral consequences ('partial basket fills convert an arb into an unhedged directional position') that clarify the risk scenario and make the usage context unmistakable.

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

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

The description is exceptionally rich in behavioral context. It explains the meaning and firing conditions of compatibility_warning, temporal_alignment, skipped_cross_type, and skipped_cross_subtype. It also discloses the real-world behavior that 'most pre-mapped topics return compatibility_warning today,' which is exactly the kind of beyond-annotation nuance that helps an agent calibrate expectations. The annotations already mark readOnlyHint and safe, but the description adds crucial caveats about data reliability.

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

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

The description is dense and long, but it earns its length. It is front-loaded with the core purpose, then structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and bolded field names. Every sentence provides operational detail or a caveat. While it could be trimmed, the complexity of the tool justifies the length, and the visual structure helps scanning.

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?

This is a highly complex tool with no output schema, so the description carries the full burden of explaining return values. It covers the response shape (each venue's leg-by-leg prices plus matched spread), the meaning of top_spreads_pp, and all safety/quality flags. It also addresses multi-step failure modes and temporal alignment. For a tool of this complexity, the description is remarkably complete.

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

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

The input schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful semantic detail beyond the schema: it explains the topic auto-mapping behavior, notes that explicit parameters 'override the topic-mapped side,' and gives examples of valid ticker/slug formats inline. This helps the agent understand the interaction between parameters and the response structure, which the schema alone does not convey.

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 crisp, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This names the exact resource (two prediction-market venues) and the operation (computing a spread). It also distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on the cross-venue comparison and the caveat that the spread is only meaningful when bet shapes match.

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 modes: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts ... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It also includes clear when-not-to-trust guidance, such as 'pre-mapped ≠ tradeable' and explanations of when compatibility_warning fires. It does not name specific alternative tools, but it gives enough context for an agent to decide when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds useful behavioral context beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and clarifies the list-all behavior when key is omitted. 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 three sentences, front-loaded with the main action, and every sentence adds value: function, use case, and scoping. No fluff or redundancy.

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

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

For a simple tool with one optional parameter, no output schema, and good annotations, the description provides complete context: purpose, usage scenarios, scoping, and relationship to siblings. The agent has enough to select and invoke this tool correctly.

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

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

Schema coverage is 100% (key described as 'Memory key to retrieve (omit to list all keys)'). The description reinforces this and adds concrete examples of key values ('the user's target ticker, an address, prior research notes'), which helps the agent understand what to pass. It goes slightly beyond the schema with usage examples.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys.' It uses a specific verb (retrieve/list) and identifies the resource (saved values/keys), and distinguishes it from sibling tools by explicitly mentioning 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?

It gives clear context for use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions complementary tools: 'Pair with remember to save, forget to delete.' However, it lacks explicit 'when not to use' exclusions, so it doesn't fully meet the 5-criteria.

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

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

The description discloses that setting mark_read:true 'flags returned events read so the next call only shows newer ones,' which is a state-changing behavior. This directly contradicts the annotation readOnlyHint=true, which implies the tool performs no mutations. Per the rubric, any contradiction between description and annotations warrants a score of 1 and triggers the annotation_contradiction flag.

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 long, front-loaded with the primary purpose, and each sentence adds valuable information: the core action, the return payload structure, filtering options, mark_read behavior, polling suitability, and an alternative API endpoint. There is no fluff or redundancy, making it highly concise and well-structured.

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

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

With no output schema, the description correctly explains what the tool returns (source, citation_uri, raw event payload). It also covers key usage aspects (filters, mark_read, polling suitability) and the alternative endpoint. However, it does not explicitly mention the 'limit' or 'unread_only' parameters, though these are well-documented in the schema. The contradiction with readOnlyHint also introduces a completeness gap regarding the tool's actual mutating potential.

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 100% of parameters with descriptions, so the baseline is 3. The description adds an example type ('sec_8k') and emphasizes the combination of type and since filters, but these are minor enhancements that do not significantly alter parameter understanding. The mark_read behavior is also described, but the schema already explains it. Overall, the description adds marginal value beyond the schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull), and the result (returns most recent alerts). This distinguishes it from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes), making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool: 'Polls work fine' indicates it's suitable for polling. It also names an explicit alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' which tells the agent when to use the HTTP endpoint instead. However, it does not explicitly compare against other sibling tools or state exclusions, so it falls short of a 5.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the multi-source fan-out to SEC EDGAR, GDELT→GNews fallback behavior, USPTO soft-fail due to API sunset, and the exact output shape. No contradictions with annotations exist.

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

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

Though long, every sentence adds unique value: usage examples, source details, fallback logic, date formats, output structure, and an alternative. It is front-loaded with the most important usage trigger and remains structured despite its density.

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 multi-source tool with no output schema, the description is remarkably complete: it explains the window parameter, each data source, fallbacks, output fields, and the main alternative. It leaves no critical ambiguity for a selecting agent.

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

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

Schema descriptions already cover all three parameters thoroughly (type enum, since formats, value examples). The tool description repeats the `since` format and adds some context about the parallel call, but it does not meaningfully expand parameter 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 starts with natural-language query patterns and then states the core function: a change feed for a company over a date window via one parallel call. It also distinguishes itself from the sibling `entity_profile` by explicitly naming when to prefer that tool 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?

It gives clear example intents ("What's new with X", "latest on Y") and explicitly says to use `entity_profile` instead for static profiles regardless of window. This provides both positive and negative usage guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond these: persistence behavior (persistent for authenticated users, 24-hour retention for anonymous sessions) and scoping ('scoped by your identifier'). Minor omission: no explicit statement about overwriting existing keys, but idempotentHint implies it.

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

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

Three sentences: purpose, usage trigger, and persistence/scoping details. Front-loaded with the verb and resource, no redundant phrases, every sentence earns its place.

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

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

For a simple write tool with full schema coverage and reasonable annotations, the description covers usage context, persistence, and companion tools. It does not explain overwrite behavior or return values, but output schema is absent and idempotentHint covers overwrites implicitly. Slight gap but not significant.

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

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

Schema coverage is 100%, so the baseline is 3. The schema already describes both parameters with examples. The description merely reiterates 'key-value pair' without adding new meaning or usage details beyond what the schema provides.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb (save) and resource (data/memory). It further clarifies the scope ('across this conversation or across sessions') and distinguishes from siblings by naming recall and forget as companion tools.

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

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

Explicit when-to-use guidance is given: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It also names alternatives for retrieval and deletion ('Pair with recall to retrieve later, forget to delete').

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, so the safety profile is known. The description adds meaningful behavioral context beyond those annotations: it details exactly what each entity type returns (e.g., ticker + CIK + company_name + citation URI for company, RxCUI + ingredient + brand for drug) and mentions that each call internally cascades through several lookup endpoints. This enriches the agent's understanding without contradicting the annotations.

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

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

The description is longer than a single sentence but is well-structured and front-loaded with usage context. It uses examples to capture intent, then systematically breaks down supported types and return values. Each sentence serves a purpose, and the layout (SUPPORTED TYPES, per-type details) aids scanning. It is not bloated relative to the complexity of the tool.

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

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

There is no output schema, so the description must explain return values, and it does thoroughly: for each type, it lists the returned identifier fields and citation URI format. It also covers accepted input variants (ticker/CIK/name, brand/generic) and explains why this tool is useful (replaces multiple lookups). Given the tool's complexity (two entity types, multiple input formats, internal cascading), the description is remarkably complete.

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

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

The schema already provides descriptions for both parameters (type and value), and coverage is 100%. The description goes further by giving concrete examples and expanding on accepted formats: for company, it accepts ticker, CIK, or name with auto-disambiguation; for drug, it accepts brand or generic names. This adds practical detail beyond the schema's basic property descriptions, making it easier for the agent to construct correct inputs.

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

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

The description opens with concrete example queries ('What's the ticker for…') and then clearly states the action: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This is a specific verb+resource pairing that distinguishes it from siblings like entity_profile. It also explicitly names the supported entity types (company, drug) and the canonical identifier returned for each.

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 an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This clearly states when to use the tool and even advises priority ordering. It also notes that each call replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use the tool or name alternatives for cases where one already has an ID.

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 idempotent, read-only, and non-destructive behavior. The description adds meaningful behavioral details: it says the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations by revealing the underlying mechanism and output structure.

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 earning its place: the first states the core compare-and-rank action, the second explains the probe mechanism and top/bottom recognition, and the third gives a concrete use case. It is front-loaded, concise, and free of redundancy.

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

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

Given no output schema, the description compensates by naming the return fields (score, confidence, signal density per entity). It also explains the tool's relationship to ai_visibility_check and notes the optional Anthropic API key, which is relevant for setup. However, it leaves out some potential edge cases (e.g., what happens when entities are unrecognized) and does not mention supported model names beyond 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?

Schema coverage is 100% with each parameter already described, so the baseline is 3. The description does not materially enhance parameter understanding—it mentions 'each entity' and 'your brand + N competitors' but the schema already covers the first-entry-subject nuance and the 2–8 range. No additional semantics are added beyond the schema.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling tools like ai_visibility_check by explaining that it probes each entity and ranks results, and the competitive audit use case ('does Claude know about us as well as our competitors?') further sharpens its purpose.

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

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

The description explicitly positions the tool for 'competitive AI-marketing audits' and the quoted question makes the intended scenario clear. It does not explicitly state when not to use it or name alternatives like ai_visibility_check for single entities, but the multi-entity comparison framing is a strong implied guideline.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior; the description adds valuable context beyond that: composite fan-out across multiple sources, a 5-30s latency warning for bundlephobia's first measurement, graceful partial-failure handling with a sources_failed field, and a detailed list of what the summary block contains. This is substantial behavioral disclosure.

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 core purpose, then usage triggers, then return details and limitations. Every sentence earns its place; it is compact yet comprehensive, with 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?

Despite having no output schema, the description fully specifies return values (summary fields, per-advisory detail, links, alternatives). It covers purpose, usage timing, ecosystem limitations, latency, and failure behavior, making it complete for agent decision-making. Complexity is high, but the description compensates well.

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

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

Schema description coverage is 100%, with both 'package' and 'version' fully described. The description does not add substantive new meaning beyond the schema (it mentions version defaults but that's already in the schema). Baseline of 3 is appropriate since schema carries the load.

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

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

The description opens with a specific verb+resource+outcome: a composite 'should I add this npm package to my project' check. It clearly distinguishes itself from sibling tools by detailing the data sources (deps.dev + bundlephobia) and the NPM-only scope, making its unique purpose unmistakable.

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

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

Explicit usage guidance is provided with direct trigger examples ('is X safe / popular / small' or 'what does adding lodash cost me'). It also states an exclusion and alternative for non-NPM ecosystems, pointing to deps.dev:version directly, which helps an agent choose between this and other 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details beyond that: embedding model (BGE-base-en), windowing (500-char overlapping), a 200K character cap with truncation flagging, and that returned passages include offsets for quote verification. This goes well beyond the safety annotations.

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

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

The description is dense but well-organized: it opens with the core action, then usage, then technical details. Every sentence adds information, though there is minor redundancy in 'saves context' and 'returns only the passages that matter.' Still, it remains appropriately sized for the complexity.

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

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

With no output schema, the description explains the return concept (passages, offsets, similarity scores) sufficiently. It also covers edge cases like input truncation, the pairing with a sibling tool, and the internal embedding approach, making the tool's behavior fully guessable for an agent.

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

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

Schema coverage is 100%, so all parameters have descriptions. The tool description adds context by clarifying that 'text' is 'the text you already pulled' with examples like SEC filings, and that 'query' is natural-language with example queries. This reinforces and enriches the schema without being redundant.

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

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

The description states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates from siblings by emphasizing operation on user-supplied text rather than querying an external database, and explicitly references ask_pipeworx_grounded as a companion. The output (top-N passages with offsets and similarity scores) is also specified.

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 when the record is too big to cram into the prompt.' It also explains the workflow pairing with ask_pipeworx_grounded, indicating when to use this tool instead of querying the whole document. This gives clear when-to-use guidance and names an alternative.

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses crucial behavioral traits: the need for OAuth account persistence, delivery channels always-on feed vs optional email/sms/webhook, SMS verification and 10/day cap, webhook auto-disable after 10 consecutive failures, and one-time HMAC signing secret. This is rich, non-redundant context that the annotations do not provide.

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

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

The description is dense with useful information and front-loads the primary purpose. Each sentence adds value (auth requirements, type examples, delivery options, caveats). It is long but proportionate to the tool's complexity. A bulleted structure could improve skimmability, but the current paragraph is still well-organized and not wasteful.

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

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

Given the tool's complexity (3 params, nested objects, multiple types, delivery options) and no output schema, the description covers an impressive amount: auth persistence, all supported types, parameter shapes, delivery channel behavior, and return value (subscription id, webhook secret). It lacks a detailed response body specification, but the coverage is strong enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description significantly enriches parameter semantics. It provides concrete examples for each type (e.g., parahms:{topic:"fed"}, items:["5.02"]), explains delivery channel constraints (verified phone, webhook security), and clarifies the required vs optional structure for clinical_trial. It adds meaning far 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 opens with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It explicitly states what the tool does and immediately distinguishes it from siblings like list_subscriptions and unsubscribe by focusing on the creation action. The scope is specific (proactive monitoring subscription) and not a tautology.

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 strong context for when to use the tool, such as requiring a Pipeworx OAuth account and explaining that anonymous/BYO cannot persist subscriptions. It also covers when each subscription type is appropriate with examples (e.g., sec_8k for 8-K filings). However, it does not explicitly mention alternative tools for viewing or deleting subscriptions (list_subscriptions, unsubscribe), so it lacks direct 'use this not that' guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses return format ('list of candidate IBANs with validity and bank name/BIC') and failure behavior ('if no suggestions are available this returns an error field'). This adds useful context beyond the annotations, though details about the error field are vague.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by return behavior and a caveat. It is concise, well-structured, and contains no redundant information.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, output, and error behavior adequately. The phrase 'Coverage is limited' is somewhat vague, leaving some ambiguity about the tool's limitations, but overall the description is complete enough.

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

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

The input schema already fully describes the single 'iban' parameter with examples and the note about spaces. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's verb and resource: 'Suggest corrected IBANs for a possibly-mistyped IBAN.' This distinguishes it from the sibling validate_iban, which likely only checks validity. The scope 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?

The description provides clear context for when to use the tool ('possibly-mistyped IBAN'), but does not explicitly name alternatives like validate_iban or state when not to use it. The usage context is implied strongly enough to guide 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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context about return structure (category-bucketed questions with exact tool+argument shape) and that it draws from a 'live catalog of thousands of tools,' which aligns with openWorldHint. It does not contradict the annotations but doesn't discuss edge cases or side effects, so not a 5.

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

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

The description is appropriately sized for an onboarding tool, front-loaded with the core purpose and use cases. It is one dense paragraph that could benefit from bullet points but every sentence earns its place by covering purpose, output, 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?

Without an output schema, the description explains what the tool returns (category-bucketed example questions with tool and argument shape). It covers the tool's role, topic parameter usage, and when to use it, making it fully complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning beyond the schema's own parameter description, merely repeating examples like 'finance', 'pharma', and 'betting'. This is adequate but not additive.

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 with specific verbs ('returns category-bucketed example questions') and identifies its resource (the live tool catalog). It distinguishes itself from siblings by naming it the 'onboarding entry point' and referencing meta-tools like ask_pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to use it ('to learn how to call the meta-tools'). It also gives usage details for the optional topic parameter, making when-to-use clear relative to 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?

Beyond the annotations (mutation, non-destructive, idempotent), the description reveals that the row is deactivated, not deleted, and that history is preserved via recent_alerts. It also discloses ownership requirements, which are critical side-effect and authorization details.

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 the action. Every clause provides valuable information: the core action, ownership, and deactivation behavior with historical data impact.

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

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

For a simple one-parameter mutation tool with annotations, the description fully explains the effect (deactivation), the authorization constraint, and the data retention consequence. No output schema exists, so omitted return info is acceptable.

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

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

The input schema already covers the only parameter (id) with description 'Subscription id (uuid) returned by subscribe.' The tool description adds 'by id' but no new format or semantic details; ownership is a behavioral constraint rather than a param semantic. Thus schema carries the load.

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 'Cancel a subscription by id,' a specific verb ('cancel') and resource ('subscription'), clearly distinguishing it from subscribe and list_subscriptions. It also clarifies that the action deactivates rather than deletes, adding precision.

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

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

It states 'Ownership is enforced — you can only cancel your own subscriptions,' giving a clear condition for use. It also notes that historical events remain available via recent_alerts, which implicitly guides the user to that tool for past data. It doesn't explicitly enumerate alternatives but provides clear contextual boundaries.

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

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

Given annotations already declare readOnlyHint, idempotentHint, and openWorldHint, the description adds substantial context: it discloses the dual-pipeline routing (SEC EDGAR fast path vs. grounded fallback), the tolerance calculation, and the verdict set (confirmed/approximately_correct/refuted/inconclusive/unsupported). It also notes the tool replaces multiple sequential calls, providing a clear behavioral picture.

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 usage examples and a decisive use-case statement. It is about six sentences long, but every sentence adds useful information (routing, verdicts, performance benefit). No wasted words, though it could be slightly more compact.

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

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

The description is comprehensive: it covers when to use, the routing logic, the judgment criteria, the return value structure (verdict, actual value, citation, reasoning), and the efficiency gain. Since there is no output schema, this description fully explains what the agent should expect, making it well-suited for tool 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?

Schema coverage is 100% for both parameters. The description adds value beyond the schema by giving concrete claim examples, explaining how tolerance_pct overrides the implied tolerance, and describing the default cap of 5%. This enhances understanding of both parameters.

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 leads with explicit natural-language patterns ("Is it true that…", "fact check") and states the tool's function as claim verification against authoritative sources. It clearly distinguishes itself from sibling research tools by focusing on verifying user claims and returning a verdict, not just answering questions or researching topics.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," providing clear context. It also explains routing by claim type (company-financial vs. other), but does not state when not to use it or name alternative tools, so it lacks explicit exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat that. It adds valuable behavioral context: accepts spaces, returns bank details when available, but bank details may be empty for non-EU/DACH countries. This openly discloses output variability beyond what annotations provide.

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

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

The description is three sentences, with the primary purpose front-loaded in the first sentence, followed by coverage limitations and input format notes. Every sentence earns its place; no redundant filler.

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

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

For a simple single-parameter tool with no output schema, the description adequately explains the return type (structural validity plus bank details), input format nuances, and geographic coverage limitations. Rich annotations cover the safety profile, making this description complete for an agent to select and invoke the tool correctly.

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

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

The input schema already fully describes the 'iban' parameter including the allowance of spaces and examples. The description reiterates the space handling but adds no additional semantic meaning beyond the schema's 100% coverage. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Validate') and resource ('IBAN'), and clearly states what the tool does: checks checksum, resolves bank details, and returns structural validity. It distinguishes itself from sibling tools like validate_claim and suggest_iban by focusing on IBAN validation.

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

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

The description provides clear context on when the tool is most effective ('Best coverage for EU/DACH banks') and clarifies what happens for other countries, implying when it should be used. While it doesn't explicitly name alternatives, the geographic scope guidance effectively tells the agent when to rely on the tool's full functionality versus when results may be limited.

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