Oeis

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

The description provides rich behavioral details beyond the annotations (which already mark it as read-only, idempotent, non-destructive). It states the probe is free for Workers AI, that Anthropic calls are passed through with BYO key, and describes the return format (score, confidence, signals, raw_response per model plus combined view). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core action and result. Every sentence is informative: what it does, default behavior, optional parameters, return format, and use cases. No unnecessary words.

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

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

Given no output schema, the description compensates by detailing the return structure (score, confidence, signals, raw_response per model + combined view). It covers all key aspects: purpose, parameters, defaults, use cases, and behavioral notes. The agent can use this tool confidently 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'entity', providing examples ('Pipeworx', 'OpenInvoice'), clarifying that '_apiKey' is only needed for Anthropic, and describing the 'context' parameter's purpose (disambiguation). This extra context improves parameter understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic and returns a score (0-100). It specifies the verb 'probe' and resource 'AI visibility', and distinguishes from siblings like 'deep_research' or 'ask_pipeworx' by focusing on visibility scoring rather than general Q&A or research.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default model and the need for an API key for Anthropic. While it doesn't explicitly contrast with sibling tools, the purpose is clear enough for an agent to decide when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, lowering the burden. The description adds genuine behavioral context beyond annotations: that the tool is a router over 5,798 tools/1,517 sources, auto-fills arguments, and returns results as stable pipeworx:// citation URIs. It stops short of discussing latency, ambiguity handling, or failure modes, but for a read-only router this is solid 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?

Front-loaded with the key directive 'PREFER OVER WEB SEARCH' and organized as directive → behavior → triggers → examples → conclusion. Every section earns its place, but the caveat 'even if web search could also answer it' appears twice, which is a small redundancy, and the precise tool/source counts could drift stale over time.

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 an entry-point router with one required string parameter and no output schema, the description supplies everything an agent needs: what to pass (natural-language questions, with examples), what happens on invocation (routing, argument filling), and what comes back (structured answer with stable citation URIs). No critical gap for correct 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 description coverage is 100%, with all six parameters documented as aliases for the single 'question' string, so the schema carries the semantic weight. The description's example questions illustrate acceptable input shape but add nothing beyond the schema's 'natural language' definition. Baseline 3 is correct given full schema coverage.

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

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

States a specific job: route factual/numeric/entity questions to the right source tool and return cited structured answers. The long domain list (SEC filings, FDA drug data, FRED/BLS, patents, real estate, weather, clinical trials, news, sports) plus the 'PREFER OVER WEB SEARCH' directive make its identity unmistakable and clearly distinguish it from a general-purpose web search fallback.

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

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

Provides explicit when-to-use guidance: a domain list, trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current'), six concrete examples, and an explicit instruction to prefer this tool over web search even when web search could answer. The 'START HERE' directive also implies routing to other tools downstream, which covers the main alternative-selection question.

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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is a live experimental edge, candidate routing changes may be active, and it falls back to nothing (fully functional router). It also discloses the current state (no candidate active) and the comparison purpose, which is useful and non-contradictory.

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 the key beta-vs-stable distinction, then the current status, then usage direction. It is a bit dense with parenthetical details (tool count, dates) but every sentence earns its place; minor redundancy like 'this IS a full working router' adds emphasis but is slightly extra.

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 (one required parameter, no output schema, no nested objects), the description is nearly complete: it explains what it is, when to use it, how it differs from the stable sibling, and its current live state. It could add an explicit statement of return shape, but since it claims identical response shape to ask_pipeworx and output schema is absent, that reference is sufficient for an agent to know what to expect.

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

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

Schema coverage is 100% and the schema documents all alias parameters clearly. The description adds the high-level fact that it takes the same arguments as ask_pipeworx, but it does not add meaning beyond the schema's alias documentation. Baseline 3 is appropriate given the schema already carries 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 states a specific verb+resource (ask a universal router, identical to ask_pipeworx) and clearly distinguishes it from the stable sibling ask_pipeworx: it is the beta variant with candidate routing improvements. It also names sibling ask_pipeworx_grounded indirectly by framing itself as the universal router, so an agent can tell them 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?

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also states no candidate is active right now, so it currently matches ask_pipeworx exactly, giving clear when-to-use guidance and enough context to choose between the beta and stable siblings.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the tool's refusal behavior, the exact success and refusal response shapes, refusal reason enum values, verbatim evidence quoting, and the extra LLM call cost. This is far richer than the structured annotations alone and gives the agent realistic expectations about grounding and failure modes.

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

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

Every sentence earns its place: the opening states the core value, the middle explains the mechanism and output contract, and the closing covers use cases and cost trade-offs. It is dense but not bloated, and the most important information appears first.

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

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

Given the simple single-question input and no output schema, the description fully compensates by specifying the complete return shape for success and refusal, the refusal reasons, evidence requirements, and when to avoid the tool. An agent has everything it needs to invoke the tool and interpret its response correctly.

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

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

Schema description coverage is 100%, so the parameter semantics are already fully documented in the schema, including aliases and natural language guidance. The description adds no additional parameter-level detail beyond describing the tool's internal argument-filling behavior, which is not necessary for the caller to compose the question correctly.

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 defines a specific mode—'Hallucination-resistant answer mode for high-stakes reads'—and clearly differentiates it from the sibling ask_pipeworx by emphasizing extraction using only the tool result, with explicit refusals instead of invented facts. This gives an agent an unambiguous understanding of what the tool does and how it differs from related tools.

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

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

The description states exactly when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the extra LLM call cost. This is explicit, actionable guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description thoroughly details behavior: resolver contract with confidence levels, parent event extraction, news fallback fields, safety short-circuits for low confidence and closed markets, wide-spread liquidity warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is comprehensive but verbose, covering many edge cases and response shapes in a single block. It is front-loaded with the purpose, but the length (multiple paragraphs) may overwhelm agents. Every sentence adds value, but some redundancy exists (e.g., repeated safety explanations).

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

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

Given the complexity of the tool (multi-source research, resolver logic, cancellation rules), the description covers most necessary context. It lacks a formal output schema but describes response shapes (result.market, result.analysis, result.evidence) in detail. Minor gaps: no explicit mention of rate limits or authentication requirements.

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

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

Input schema coverage is 100% (all three parameters documented). The description adds value by explaining the 'market' parameter accepts slug, URL, or text; 'depth' enum is mentioned; 'include_raw' has a detailed explanation of default false and when to use true, which goes beyond the schema description.

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 ('Research'), resource ('Polymarket bet'), and action ('pulling the relevant Pipeworx data for it in one call'). It specifies multiple input formats (slug, URL, question text) and output types (evidence packet, market-vs-model comparison). While sibling tools like polymarket_arbitrage exist, the unique 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 explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifiers (crypto_price, fed_rate, etc.) and fan-out examples. It warns about low_confidence_match blocking and closed market behavior, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations indicate read-only and idempotent behavior. The description adds details: parallel call, correct fiscal year handling, sorted results, and citation URIs. No contradictions.

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

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

The description is front-loaded with key examples and instructions. Every sentence adds value, though slightly verbose. Essentially 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?

No output schema, but description explains return format: paired data and citation URIs. Adequate for a 2-parameter tool with no nested objects.

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

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

Schema coverage is 100%, but description adds value with concrete examples (e.g., 'AAPL','MSFT' for companies) and explains how off-calendar years are handled, going beyond the schema.

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

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

The description uses specific verbs like 'side-by-side comparison' and 'pulls', clearly stating it compares 2-5 entities of type company or drug. It distinguishes from sequential lookups by stating it replaces 8-15 sequential calls.

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

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

The description provides explicit when-to-use cues with example queries and states 'ALWAYS PREFER over sequential single-pack lookups'. It does not explicitly mention exclusions, 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 mark it read-only, idempotent, open-world, and non-destructive, and the description goes well beyond them. It discloses account requirements, latency expectations, gap[] handling, never-invented findings, contradiction scans, hop fields, and resolvable citation URIs. This gives an unusually complete picture of what the tool will actually do.

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 nearly every sentence carries decision-relevant information: account prerequisites, alternative tool routing, scope limitations, return structure, depth semantics, latency, and citation guarantees. It is front-loaded with the most critical gate (account required) and the fallback tool. A small amount of redundancy with the schema's depth explanation prevents a perfect score, but it is still disciplined for this 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?

There is no output schema, so the description must explain return values, and it does: findings packet contents, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers failure/limitation behavior and expected latency. An agent has everything needed to decide whether to call it and how to interpret the response.

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

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

Schema coverage is 100%, but the description adds meaningful operational context: depth tiers are tied to paid plans, defaults, hop behavior, and latency differences. It also gives concrete example questions that illustrate how 'question' should be phrased. This adds practical value beyond the schema's field descriptions.

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

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

States a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources, not open-web search. It clearly distinguishes itself from ask_pipeworx by describing its decomposition, parallel routing, and findings-packet behavior. The examples of broad/multi-part questions make the intended use 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 says to use ask_pipeworx instead when not signed in and for single lookups, while positioning deep_research as best for broad/multi-part questions over structured data. It also clarifies that 'thorough' requires a paid plan, giving agents an actionable selection criterion. This is strong when/when-not guidance relative to the sibling set.

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

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

Annotations indicate read-only and idempotent. Description adds that results include full schemas with curated examples and are ready to call directly, which is behavioral context beyond annotations.

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

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

Description is two sentences plus a list; front-loaded with main action. Could be slightly more concise by reducing the domain list, but overall 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?

Covers purpose, usage, behavior, and output nature. Does not cover error cases or empty results, but given the tool's nature as a search, this is acceptable.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minimal additional semantics beyond stating that query is a natural language description, matching the schema. Baseline 3 due to full coverage.

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

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

The description clearly states it finds tools by describing data/task, listing many domains. It distinguishes from siblings by being a discovery tool that returns ready-to-call results with full schemas, which is unique among sibling tools.

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

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

Explicitly says to use when browsing or discovering tools, and to call FIRST when many tools are available. Does not explicitly list when not to use, but provides strong positive 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?

Even though annotations already declare readOnly, openWorld, and idempotent hints, the description adds substantial behavioral context: it fans out across multiple named sources, reports sources_used/sources_failed, clarifies that an empty section means no data rather than a bug, and explains private-company behavior via resolved:false plus notes. This goes far beyond what the annotations convey.

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

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

The description is dense and slightly long, but it front-loads the core purpose and user intents before diving into source details. Every sentence carries useful information, though the output source enumeration and parenthetical examples could be tightened without much loss.

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 available, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates the sections (cik, filings, fundamentals, patents, federal contracts, FDA products, hiring, news, LEI), coverage semantics via sources_used/sources_failed, and edge-case behavior for private companies and name resolution. This is complete enough for an agent to invoke the tool confidently.

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

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

Schema coverage is 100%, but the description adds meaningful parameter semantics: 'type' accepts 'company' or 'ticker' interchangeably, 'value' can be a ticker, zero-padded CIK, or company name, and names resolve through SEC EDGAR's company-name match. It also mentions resolved_from/resolved_to when a name is supplied, which is not present in the schema, helping the agent understand result semantics.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme', 'brief me on Tesla') and states the core deliverable: a 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company) and the specific fan-out mechanism, making the tool's purpose unmistakable and clearly distinct from single-source lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which tells the agent when to choose this tool over alternative lookup paths. It also explains accepted input forms (ticker, CIK, company name) and the graceful handling of private companies, so the agent knows what to expect in edge cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds 'delete' and 'previously stored' but doesn't elaborate on error behavior or permanence. Minimal additional value beyond annotations.

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

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

Two efficient sentences. First states core action, second provides usage guidelines. No fluff.

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

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

For a simple single-parameter deletion tool with no output schema, the description covers purpose, usage context, and sibling tools. Complete for its complexity.

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

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

Schema coverage is 100% and schema already describes the 'key' parameter. Description does not add any extra detail about key format, constraints, or behavior.

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?

Clear verb-resource pair: 'Delete a previously stored memory by key'. Immediately distinguishes from siblings like 'remember' and 'recall' which are store and retrieve respectively.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data'. Also names complementary tools 'remember and recall'.

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

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

Discloses fetching the page, extracting title/description/key links, and emitting standard markdown format. Complements annotations (readOnlyHint, idempotentHint) with behavioral details. No contradiction.

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

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

Concise three-sentence paragraph, front-loaded with main action, includes target audience and use cases without redundancy.

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

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

With full schema coverage, rich annotations, and clear description of output and behavior, the definition is complete for informed agent decision-making.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds no extra meaning beyond schema (e.g., default/max already in schema). Baseline score applies.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, with specific verb and resource. Distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

Provides explicit use cases for getting a client's site indexed, drafting for own project, or auditing competitors. Lacks negative guidance ('when not to use') but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, aligning with the description's 'Fetch' operation. The description adds value by detailing input flexibility (prefix, zero-padding) and listing returned fields (name, terms, comments, formulas, etc.). No contradictions.

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

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

Three sentences with the main purpose first, followed by input examples and output details, ending with a usage hint. Every sentence is informative, no waste. Highly efficient.

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

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

Given no output schema, the description lists seven return fields (name, terms, data, comments, formulas, keywords, offset, author, reference count), covering expected results. It doesn't specify data types or structure, but for a simple fetch tool, this is sufficient and 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 schema covers the single parameter 'id' with 100% coverage, including examples. The description complements this by providing concrete examples (e.g., A000045, A000040) and clarifying valid input formats. This adds meaning but doesn't drastically exceed the schema's 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 fetches a single OEIS integer sequence by its A-number. The verb 'fetch' and resource 'OEIS integer sequence' are specific. It also distinguishes from the sibling 'search_sequence' by focusing on retrieval by exact ID.

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

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

The description advises using this tool to 'get the formula or mathematical description of a known sequence,' implying it is for when the A-number is known. It does not explicitly state when not to use it, but the sibling 'search_sequence' is implied for lookup by name or description. Adequate 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?

Adds value beyond annotations by specifying returned fields (id, type, etc.) and that it lists active subscriptions by default. Annotations already cover safety and idempotency, so description complements well.

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

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

Two concise sentences front-loading purpose and return fields, followed by usage guidance. 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?

Complete for a simple read-only tool with one optional parameter, no output schema. Describes return fields, usage context, and default behavior adequately.

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. Description implies the default behavior (active only) but adds no new detail about the include_inactive parameter beyond schema. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Explicitly says 'use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context. Does not explicitly exclude scenarios, but the guidance is sufficient.

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

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

Annotations are all false, so the description carries the burden of disclosure. It adds useful behavior: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, returns a claim_token for later lookup, and team reads digests daily. This goes well beyond the annotations, though it doesn't specify any side effects beyond submitting a report. A small gap is what constitutes an 'identifier' for rate limiting, but overall it's 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 longer than the high-calibration example but every sentence adds value: purpose, use cases, exclusions, claim-token flow, rate limits, and roadmap impact. It is front-loaded with the core action and uses a logical flow. However, it could be slightly tighter; the 'Not sure?' sentence about tool names could be integrated elsewhere. Still, it's concise relative to its content 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?

Given there is no output schema, the description covers the expected outputs (claim_token, later status) and explains the broader context (daily digest, roadmap signal, rate limit). It also clarifies what not to include (end-user's prompt) and how to identify Pipeworx tools. This is complete enough for a feedback tool, though a note about what happens after filing (e.g., whether there is a confirmation) would round it out.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds workflow context for the claim_token parameter ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and advises on how to write the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enhances the parameter semantics beyond the schema's individual 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 and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by scoping it to feedback about Pipeworx tools and explicitly excluding tools from other MCP servers, which differentiates it from every sibling tool.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a direct exclusion criterion: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance with alternatives listed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: caching details (5min-1h), data source (CF analytics-engine), and no PII. No contradictions.

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

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

Description is concise (3 sentences plus bullet list) with front-loaded purpose and return values. Every sentence adds value; no redundancy or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description covers purpose, use cases, caching, and data origin. Complete enough 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 a well-described enum parameter. The description adds semantic context about shorter windows surfacing hot trends and longer windows showing steady-state demand, which enhances understanding beyond the schema.

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

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

Description clearly states it returns top tools, packs, and call volume over a recent window. The verb 'Returns' is specific and the resource (trending usage on Pipeworx) is well-defined, distinguishing it from sibling tools like discover_tools or 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?

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases). While it doesn't explicitly state when not to use or list alternatives, the use cases are clear and cover common 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?

The description goes beyond annotations by detailing internal checks (semantic anchor, partition filter, fill check against live CLOB depth) and conditions that yield null signals. Annotations already indicate safe, read-only behavior, and the description adds full behavioral context without contradiction.

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

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

The description is lengthy but well-structured, starting with purpose then detailing each mode. While it is dense with information, it avoids redundancy and fronts the core functionality. Minor verbosity in technical details is justified by tool 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?

Despite no output schema, the description fully explains the response structure (opportunities array, partition_check object, fill check details). It also covers safety checks and references complementary tools, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so the schema documents both parameters. The description adds value by explaining mode-specific usage, providing example slugs, and clarifying how each parameter triggers different analysis pathways.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges by focusing specifically on arbitrage with these methods.

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also references polymarket_fill_risk for custom sizing and provides fill check 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 indicate read-only, idempotent, non-destructive. Description adds substantial behavioral context: model families, response structure, caching, edge calculation details, and warnings (e.g., 24h move). No contradictions.

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

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

Well-structured with clear sections (model families, response, knobs). Verbose but each sentence adds value. Could be slightly more concise, but appropriate for complexity.

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

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

No output schema, but description fully compensates by detailing response structure (by_segment, diagnostics, edge fields). Covers caching, parameter interactions, and edge cases (e.g., Fed candidates). Complete for an agent to use.

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

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

Input schema has 100% coverage with descriptions. Description enriches each parameter with practical guidance (e.g., slippage_pp explaining typical costs, min_liquidity suggesting threshold). Adds value beyond schema.

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

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

Description clearly states verb ('scan') and resource ('top Polymarket markets'), and distinguishes from siblings by focusing on disagreement between Pipeworx data and market price. It is specific and actionable.

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?

Describes when to use ('what should I bet on today') and provides detailed knob descriptions for filtering. However, lacks explicit comparison to sibling tools or clear when-not-to-use scenarios beyond the Fed note.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds substantial behavioral context: data from daily snapshots, decay computed from daily closes, history bounded by 60-day TTL, gaps when no scan, sign meaning in edge_pp_net. No contradiction with annotations.

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

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

Description is moderately long but each sentence adds value. Core purpose front-loaded, followed by parameter details and response format. Could be slightly tightened but no wasted words.

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

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

No output schema provided, so description must explain return values. It thoroughly describes tracked[], expired[], snapshot_dates[], including field meanings. Also documents limits (TTL, decay computation). Complete for a complex tool.

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

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

Schema descriptions cover 100% of parameters. Description adds value by explaining default values (14 days, 1wk) and acceptable ranges (clamp 2-30, window options). Also describes response structure, compensating for lack of output schema.

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

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

Clearly states the tool tracks edge persistence and decay telemetry from polymarket_edges snapshots. Distinguishes itself from sibling tools like polymarket_edges by focusing on time-series trends and decay. Specific verb ('tracks') and resource (daily snapshots) defined upfront.

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?

Answers the explicit question 'how long has this edge existed and is it shrinking?', implying when to use. Provides context on trade significance (fresh vs. old edges). Could more explicitly state alternatives, but sibling list suggests distinct purpose. Clear context on data source and limits.

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, openWorldHint, idempotentHint, and not destructive. The description adds context beyond annotations: it walks the order ladder, returns verdicts (clean/degraded/cannot_fill), and warns about risks like unhedged directional positions. No contradictions.

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

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

The description is approximately 10 sentences, which is long but necessary given the complexity. It front-loads the core purpose and uses capitalization for emphasis. It could be more structured with bullet points but remains efficient and information-dense.

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

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

Despite no output schema, the description comprehensively lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and risk details (thin_legs, forced_directional_risk). It covers all necessary aspects for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% (all four parameters have descriptions). The description adds meaning by explaining the interplay between market/event and side, default values, and the interpretation of size_usd in different modes. It enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and specifies the verb 'check' and the resource 'fill risk.' This differentiates it from siblings like polymarket_arbitrage and 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 tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale, such as 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position.' It also states required parameters.

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already set, the description adds substantial behavioral context: it explains that legs with unknown metric_type or match_subtype are never paired, that compatibility fields can be non-empty even when matched_pairs > 0, that pairing is always keyword-based and unverified, and that null temporal_alignment means unknown rather than aligned. The fee disclosure stating that every spread is gross, not net tradeable edge, is especially valuable.

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

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

The description is long but dense, with every section serving a purpose: modes, response shape, safety fields, compatibility codes, skip counters, and fee caveats. It uses uppercase labels and front-loads purpose before enumerating details. It could be restructured into clearer sections rather than one large prose block, but the length is largely justified by the tool's complexity and safety-critical interpretation rules.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, per-entry flags, compatibility fields, temporal alignment semantics, skipped leg counters, low_confidence_pairs, and fees_note. It also covers the null-means-unknown semantics and the unverified nature of pairing. For a comparably complex tool, nothing critical 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?

Although the schema already documents all three parameters at 100% coverage, the description adds meaning beyond the schema: topic is a curated shortcut list with examples, explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and both modes run the identical token-overlap matcher. This prevents an agent from assuming different semantics for each mode.

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

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

The description opens with a specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly names the resource, the computation, and the cross-venue scope, and it distinguishes this tool from same-venue or other research siblings by emphasizing cross-venue comparison. The two modes and response summary further reinforce what the tool does.

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

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

The description clearly explains when to use the tool — for matching questions across Kalshi and Polymarket — and distinguishes the two invocation modes: pre-mapped topic shortcuts versus explicit ticker/slug pairings. It also gives important when-not guidance: pre-mapped topics often return compatibility warnings and are not automatically tradeable, and spreads are gross, not net of Kalshi fees. It does not explicitly name alternative sibling tools, so it stops 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping ('Scoped to your identifier') and pairing with remember/forget, which goes beyond the annotations.

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

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

Three sentences, each earning its place: first defines action, second gives use cases, third explains scoping and pairing. No redundancy, front-loaded with purpose.

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

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

For a simple retrieval tool with no output schema, the description covers input behavior, typical use cases, and scoping. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description repeats this essentially but adds context about listing all keys in the first sentence. The addition is marginal.

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

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

The description clearly states the verb ('Retrieve' or 'list'), the resource ('a value previously saved via remember' or 'all saved keys'), and distinguishes from sibling tools (remember, forget). It provides concrete use cases like 'user's target ticker, an address, prior research notes'.

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

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

The description explicitly states when to use this tool ('Use to look up context the agent stored earlier without re-deriving it from scratch') and mentions scoping. It lacks explicit 'when not to use' or alternatives among the large sibling list, 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, idempotentHint, etc. Description adds valuable behavioral details: the effect of mark_read (flags events read so next call only returns newer ones), and the feed URL alternative. No contradictions.

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

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

Two sentences, each earning its place. Front-loaded with purpose, then return fields, filters, and behavioral notes. No fluff.

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

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

For a read-only tool with 5 parameters and no output schema, the description fully explains return fields, filtering, marking read, and alternative access. All necessary context is provided.

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. Description adds practical usage examples (e.g., 'sec_8k' for type, ISO timestamps for since) and explains the behavior of mark_read beyond the schema's 'Flag the returned events read'.

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 starts with a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly stating what the tool does. It distinguishes from siblings by being the only tool that retrieves subscription 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?

Provides explicit context: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This hints at when to use this tool vs. an alternative. However, it doesn't explicitly state when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes well beyond by explaining fan-out to multiple sources, failure modes, fallback logic, and return format. 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 packed with useful information and is front-loaded with example queries. However, it is a single dense paragraph; splitting into sections could improve readability slightly.

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

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

Even without an output schema, the description describes the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers input, behavior, and output comprehensively.

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 all parameters described. The description adds value by clarifying the since parameter with examples and best practice ('30d' or '1m'), and explaining value accepts ticker or CIK.

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

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

The description clearly states it provides a change feed for a company covering SEC filings, news, and patents. It uses specific verbs ('change feed', 'fans out') and distinguishes from sibling tool entity_profile by explicitly directing when to use that instead.

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

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

The description provides explicit example queries and explains when to use entity_profile for static profiles. It also details fallback behavior for news sources (GDELT preferred, GNews when rate-limited) and mentions PatentsView API sunset.

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?

Adds storage behavior beyond annotations: persistent memory for authenticated users, 24-hour retention for anonymous. 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?

Well-structured single paragraph: purpose first, then usage, then details. Every sentence adds value; no fluff.

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

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

Given simple tool with 2 params and no output schema, description covers all needed aspects: purpose, usage, behavior, parameter semantics, and lifecycle.

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

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

Schema coverage is 100%, but description adds value with example keys and explains the purpose of storing any text. Clearly maps parameters to use cases.

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

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

The description clearly states the tool saves data for reuse across sessions, with specific verb and resource (save data). It distinguishes from siblings by mentioning recall and forget.

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

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

Explicit when-to-use guidance with examples of what to save (resolved ticker, target address, etc.). Notes alternatives (recall, forget) and context (authenticated vs anonymous sessions).

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, idempotent, openWorld), the description discloses substantial behavioral detail: it cascades through multiple lookup endpoints internally, degrades gracefully (returns EDGAR identifiers even if GLEIF/OpenFIGI are down), labels each identifier with its source, explicitly lists unresolved identifiers under `unresolved`, and explains the FIGI matching nuance (non-equity instruments resolve, but ambiguous names return candidates). This far exceeds what annotations convey and gives the agent a clear mental model of what to expect.

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

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

The description is long and dense, but every sentence adds value. It is front-loaded with examples and the 'Use FIRST' directive, then progressively details supported types, fallback behavior, and parameter nuances. While not concise in a word-count sense, it is well-organized and earns its length given the multi-source complexity. The structure could be slightly tightened (e.g., separating the huge run-on sentence about company type), but it is not bloated with 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?

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior, ambiguity handling) and the absence of an output schema, the description does an excellent job of covering what an agent needs to know. It explains return behavior (figi_candidates, unresolved list, source labels), edge cases (bonds without tickers, ISIN-to-LEI mapping, foreign issuers), and input constraints. Nothing critical for correct invocation 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% (both parameters documented), so baseline is 3. However, the description adds substantial meaning: it explains the `type` enum options in practical terms (the 'company' type covers CIK, ticker, name, and even ISIN mapping to legal entity), and for `value` it provides detailed guidance about passing only the entity name, warns against trailing security-class words, and gives examples. This goes well beyond the schema and directly improves correct invocation.

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

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

The description clearly states the verb (resolve) and the resource (user-spoken names to official identifiers). It lists concrete examples (ticker, CIK, LEI, RxCUI) and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from siblings that likely operate on already-resolved entities. It leaves no doubt about what the tool does and when it is the right choice.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what happens in ambiguous cases (asserts nothing, returns figi_candidates) and how ISIN inputs are handled. It does not name specific sibling tools to avoid, but the 'Use FIRST' directive and the fact it replaces 2-3 manual lookups make the intended context clear. It could have been stronger by explicitly saying when NOT to use it, but the guidance is solid.

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 readOnly, idempotent, openWorld, non-destructive. Description adds that it internally calls ai_visibility_check and returns ranked list with score/confidence/signal density. No contradictions.

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

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

Two sentences plus parenthetical example. Concise and front-loaded with purpose and method. Every sentence provides 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?

Covers purpose, method (probes with ai_visibility_check), output (ranked list with score/confidence/signal density). No output schema but description sufficient for a comparison tool with good annotations.

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

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

Schema coverage is 100%. Description adds context: first entity is subject, models default to workers-ai, context disambiguates, _apiKey optional. Adds meaningful information beyond 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?

Clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks, and surfaces recognition. Concrete example ('does Claude know about us as well as our competitors?') distinguishes it from single-entity sibling ai_visibility_check.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and implies comparison use case. No explicit when-not or alternatives mentioned, but sibling list includes ai_visibility_check for single entity, allowing inference.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint. The description goes beyond by explaining partial failure behavior (bundlephobia timeout, sources_failed listing) and multi-source fan-out. 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 front-loaded with the core purpose and uses efficient multi-sentence structure. Each sentence adds distinct value (purpose, data sources, usage guidance, ecosystem scope, failure behavior). No wasted words.

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

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

Despite lacking an output schema, the description fully documents the return structure (summary fields, per-advisory details, links, alternatives) and handles edge cases like partial failures. Given the tool's complexity, this is comprehensive.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. The description confirms the npm ecosystem and default version behavior but does not add significant new meaning beyond what schema descriptions already provide.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, specifying it combines deps.dev and bundlephobia data. It differentiates from other ecosystems by noting NPM-only scope in v1, and no sibling tool offers the same functionality.

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

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

Explicitly instructs to use when agent asks about safety, popularity, or size of an npm package. Provides clear when-not-to-use for other package ecosystems by directing to deps.dev:version directly. This is actionable guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds concrete behavior: returns up to 10 results per page, supports pagination via the 'start' parameter, and lists returned fields (A-number, name, terms, keywords, author, offset). No contradictions.

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

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

The description is three sentences, front-loaded with the tool's main purpose, and every sentence adds essential information without redundancy.

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

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

Despite no output schema, the description fully explains what the tool returns (up to 10 sequences per page with specific fields) and how pagination works. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, with schema descriptions for both parameters. The description adds value by providing usage examples and clarifying that the 'query' can be comma-separated integers, an A-number, or free-text, and that 'start' is a pagination offset.

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

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

The description clearly states it searches the OEIS for integer sequences, and specifies three distinct use cases: identifying a sequence from its terms, looking up by A-number, or free-text keyword search. This contrasts with sibling tools like 'get_sequence', which likely retrieves a single sequence by ID.

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

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

The description explicitly explains when to use the tool (for sequence lookup by terms, A-number, or keywords) and mentions pagination. While it does not explicitly state when not to use it or list alternatives, the context from sibling tools like 'get_sequence' provides implicit 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 annotations (readOnlyHint, etc.), the description discloses technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flag. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. First sentence states core purpose, then constraints, then usage guidance, then technical details. Every sentence adds value; no redundancy.

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

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

Given no output schema, the description explains what is returned (passages, offsets, scores) and how it integrates with other tools. It covers input limits, algorithm, and use case, making it fully informative.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying text max length (~200K), limit default (5), and query examples. This is helpful but not excessive.

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 semantic search inside a fetched record, specifies the input (text and query), output (passages with offsets and similarity scores), and distinguishes from sibling tools like ask_pipeworx_grounded. The verb 'search' and resource 'inside a fetched record' are specific and 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?

Explicitly states when to use ('when the record is too big to cram into the prompt') and provides an alternative pair ('Pairs with ask_pipeworx_grounded'). This helps the agent decide context.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description details behavioral traits: requires OAuth account, supports specific types with parameter examples, delivery channels with constraints (SMS rate cap, webhook auto-disable after 10 failures), and the always-on feed. No contradictions.

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

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

The description is well-structured and front-loaded with the core purpose and return value. It covers requirements, types, and delivery details in a logical order. It is somewhat lengthy but every sentence adds necessary information, with minimal redundancy.

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

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

Given the complexity (no output schema, nested objects), the description covers purpose, requirements, parameter details, and delivery options comprehensively. It could mention idempotency behavior or error cases, but the idempotentHint partially covers that. Overall, it provides enough context for correct usage.

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

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

The input schema has 100% coverage, but the description adds significant value by explaining the meanings of enum values, providing concrete examples for each type, detailing delivery channel behavior (e.g., webhook signing, SMS verification), and specifying required vs optional sub-parameters (e.g., 'sponsor or condition required' for clinical_trial).

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and specifies it returns the new subscription id. It differentiates from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts' by its focus on creation.

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 the prerequisite of a Pipeworx OAuth account and that anonymous/BYO users cannot persist subscriptions. It also provides type-specific guidance and delivery channel options, though it could more directly state when not to use this tool versus alternatives like 'ask_pipeworx' for one-off queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it returns category-bucketed examples with exact tool+argument shapes, can be called with no arguments or a topic. No contradictions.

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

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

The description is somewhat verbose but front-loaded with aliases and purpose. Each sentence earns its place, though it could be slightly more concise. Structure is clear.

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 collection of 33 sibling tools and no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shape) and how to invoke it. It is complete and well-positioned.

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 provides 100% coverage with description for 'topic'. The description adds context that the topic is optional and lists valid focus areas (finance, pharma, etc.), enhancing the schema's 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 explicitly states the tool's purpose: onboarding entry point that returns category-bucketed example questions. It clearly distinguishes from siblings like 'ask_pipeworx' and 'entity_profile' by focusing on discovery and examples.

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

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

The description gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic vs. calling with no arguments, covering when to use this 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?

The description adds behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical data. Annotations already note it's not read-only and not destructive, and the description aligns well.

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

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

Three concise sentences, front-loaded with purpose, then ownership, then effect. No wasted words.

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

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

The description covers input, behavior, and effect sufficiently. Missing return value or error details, but for a simple mutation tool with no output schema, it is reasonably complete.

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

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

Only one parameter with 100% schema coverage. The description adds that the id comes from 'subscribe', which is helpful context beyond the schema's description.

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 cancels a subscription by ID, distinguishing it from subscribe and list_subscriptions. It specifies the verb 'cancel' and the resource 'subscription', and highlights ownership enforcement.

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

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

The description implies when to use: to cancel your own subscriptions. It does not explicitly list alternatives or when-not-to-use, but the ownership enforcement gives clear context.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds significant context beyond annotations: the two pipeline routes (SEC EDGAR vs grounded), the exact verdict set, the distinction between 'could_not_verify' (pipeline failure, not evidence) and 'unsupported' (no source coverage), and the presence of verification_error. No contradictions with annotations.

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

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

The description is dense but every sentence contributes: trigger phrases, purpose, routing logic, return format, critical caller-facing caveats, and efficiency note. It is front-loaded with the most important use-case first and uses caps for the 'IMPORTANT' warning, making it scannable despite length.

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

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

Given the tool's complexity (two pipelines, six distinct verdicts, error semantics) and the absence of an output schema, the description covers all essential aspects: return values, citation format, error handling, and the crucial semantic of 'could_not_verify' vs 'unsupported'. It leaves little ambiguity 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 already provides 100% coverage for both parameters, including examples for 'claim'. The description adds extra semantic value by explaining the tolerance_pct override behavior, default cap of 5, and recommendation for hallucination detection (1–2%). This goes beyond the schema's plain definition.

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 natural-language trigger phrases and explicitly states the tool verifies factual claims against authoritative sources, returning a verdict. It clearly distinguishes itself from general Q&A (ask_pipeworx) and research (deep_research) by focusing on claim verification and even notes it replaces a multi-step pipeline.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates the fast path for company-financial claims from the grounded pipeline for other factual claims, and even explains efficiency benefits over sequential calls. This gives clear when-to-use guidance without naming sibling alternatives explicitly.

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