Unpaywall

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. Description adds important behavioral details: default free model, BYO key for Anthropic (cost incurred directly), and return structure (per-model fields). 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, each adding essential information. First sentence states purpose and output, second explains models and key usage, third lists use cases. No redundant text.

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

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

No output schema exists, but description partially specifies return fields (score, confidence, signals, raw_response + combined view). Covers the main aspects of a moderately complex tool; slight gap on exact JSON structure but sufficient for selection.

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

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

Schema coverage is 100% (all parameters have descriptions). Description adds value by explaining the default model, that _apiKey is passed directly to Anthropic, and that context helps disambiguate. This goes beyond the schema descriptions.

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

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

Description clearly states the verb 'Probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Does not explicitly state when not to use, but the context is clear and the tool is safe (read-only), so the guidance is adequate.

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 this read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those hints by explaining that the tool acts as a router: it selects among thousands of tools, fills arguments, and returns structured answers with citation URIs. This helps an agent understand the internal indirection and output format, though it doesn't mention rate limits or failure modes, which are minor for a read-only tool.

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

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

The description is dense but overly long and runs together in large block paragraphs. It front-loads the critical 'PREFER OVER WEB SEARCH' directive and uses bold effectively, but the combined domain list, examples, and five sibling tool comparisons create a wall of text that would be easier to parse with bullets or shorter sentences. Every sentence earns its place, but the structure hurts scannability.

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

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

For a router tool with no output schema, the description provides comprehensive context: scope (authoritative real-world data), examples, routing behavior, citations, and explicit alternatives to sibling tools. The main gap is that it doesn't describe how errors or unanswerable queries are handled, but the overall picture is strong enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with 'question' documented as a natural-language request and all other five parameters explicitly aliased. The description's examples add some semantic flavor by showing realistic queries, but the schema already provides sufficient parameter understanding, so the description adds little beyond a baseline-3 level.

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 that the tool routes factual questions to one of 5,798 verified-source tools and returns structured answers with stable pipeworx:// citation URIs. It opens with a strong directive 'PREFER OVER WEB SEARCH' and explicitly distinguishes itself from siblings like compare_entities, entity_profile, ask_pipeworx_grounded, and deep_research, so an agent can clearly recognize what this tool does and is not.

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

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

The description gives explicit when-to-use guidance: prefer over web search for authoritative structured data, use for trigger phrases like 'what is', 'look up', and 'get the latest', and even if web search could answer. It also names alternatives with specific conditions: compare_entities for side-by-side comparisons, entity_profile for deep dives, ask_pipeworx_grounded for user-document grounding, and deep_research for broad multi-part questions. This is a complete usage map.

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

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

The annotations already declare readOnly/openWorld/idempotent hints, so the safety profile is covered. The description adds meaningful behavior beyond those annotations: the routing may differ when a candidate is under test, no candidate is active right now, and the tool currently behaves identically to ask_pipeworx. It does not detail the response shape, but that is disclosed as identical to ask_pipeworx, so the agent can infer the format.

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

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

The description is a single dense paragraph but every sentence earns its place: what it is, what differs, current state, usage instruction, comparison purpose, and a clarifying note that it is not a fallback. The front-loaded naming of the beta nature and the explicit 'no candidate is active right now' are exactly what an agent needs first. No filler.

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

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

The description is complete for an experimental router variant with a single required parameter. It states the current behavior, the experimental condition, how to use it, and why it exists. It references ask_pipeworx for response-shape details, which is sufficient given no output schema. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters, including the aliases. The description says 'same arguments' but does not enumerate them or add semantic detail beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting, and the description's pointer to ask_pipeworx adds little parameter-specific 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 states a specific verb+resource: it is the beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It also clearly distinguishes itself from the stable ask_pipeworx by noting when a candidate is active. The explicit mention that it currently matches ask_pipeworx exactly prevents agent confusion 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?

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It clarifies that it is a full working router, not a fallback, which preemptively answers a likely agent decision point. This is strong when-to-use and alternative-selection guidance.

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

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

The description adds substantial behavior beyond the readOnly/idempotent annotations: refusal reasons, exact return shape, grounding constraint, extra LLM call cost, and the high-stakes use case. 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 dense but every sentence earns its place: purpose, mechanism, return shape, refusal behavior, use cases, and cost tradeoff are all covered without fluff. Front-loads the most important distinction (hallucination-resistant) before details.

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

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

At 6 parameters with no output schema, the description compensates thoroughly by documenting the return contract, refusal reasons, and selection criteria. An agent has enough to invoke it appropriately and interpret results correctly.

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

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

Schema coverage is 100%, and the schema already documents the question parameter and its aliases. The description doesn't add parameter-level detail, which is acceptable because the schema carries the full burden.

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

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

States a specific verb and resource: an answer mode that extracts grounded answers using only tool results. The description explicitly contrasts with ask_pipeworx while also naming it as the same routing, distinguishing this tool's behavior clearly.

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 selection guidance: use when answers will be quoted, cited, or acted on and facts must not be invented; prefer ask_pipeworx for casual lookups. This makes the when-to-use and when-not-to-use decision unambiguous.

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

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

The description adds extensive behavioral context beyond annotations: it explains low-confidence resolution short-circuit, closed market handling, wide spread illiquidity, cancellation rule parsing, news fallback mechanisms, and the parent event extractor. Annotations indicate readOnlyHint=true and idempotentHint=true, which are consistent, but the description enriches the agent's understanding of edge cases and safety behaviors.

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 very long and detailed, containing multiple paragraphs, examples, and technical edge cases. While well-structured with section headers, it could be more concise. Every sentence earns its place, but the sheer length may reduce scanability for an AI agent. A tighter focus on essential behavioral rules would improve clarity without sacrificing completeness.

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, absence of an output schema, and 3 parameters, the description is remarkably complete. It covers all major aspects: input format, process, fan-out examples, response shapes, resolver contract, parent event extraction, news fallbacks, safety mechanisms, and cancellation rules. An agent can confidently invoke this tool with minimal ambiguity.

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

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

Schema coverage is 100% (all 3 parameters described), so baseline is 3. The description adds value by clarifying the 'market' parameter's accepted formats and giving examples. For 'depth' and 'include_raw', it provides behavioral context (e.g., 'quick = 2-3 evidence sources', 'false keeps responses under ~20KB'), which helps 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 identifies the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), describes the process (resolves, classifies, fans out), and states the output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples of fan-out for different bet types. However, it does not mention when not to use it or compare to specific sibling tools like polymarket_edges, leaving some ambiguity about alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description adds: parallel API call, data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 well-structured, starting with trigger phrases and then detailing behavior. It is slightly verbose but every sentence adds value, making it efficient overall.

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

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

Covers typical use cases, data sources, behavior, and efficiency gains. Lacks mention of limitations (e.g., historical range, rate limits) but is sufficient for a read-only, open-world tool with no output schema.

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

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

Schema coverage is 100% and parameters already described. Description adds examples ('AAPL','MSFT','ozempic') but does not add new semantic meaning beyond schema.

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

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

Description clearly identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It distinguishes from sequential lookups and provides specific trigger phrases.

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 preference over sequential single-pack lookups and provides context for when to use (comparing entities). Does not mention when-not-to-use, but positive guidance is strong.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral context: account/paywall requirements, latency ranges, facet decomposition and parallel routing, explicit gaps for unanswered facets, no-invention guarantees, contradiction detection, semantic excerpting, and fetchable citation URIs. No contradiction with the annotations.

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

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

The description is long but dense, and every sentence contributes critical operational context such as auth, scope, alternatives, and result format. It is front-loaded with the account requirement, though the wall-of-text style could benefit from clearer structure.

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

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

With no output schema, the description compensates by thoroughly describing the findings packet, citation semantics, contradictions, gaps, latency, and auth requirements. It gives an agent enough information to invoke the tool and interpret its results correctly.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds extra semantic value by giving concrete example questions and explaining how each depth level changes hop behavior and gap recovery beyond the schema text.

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

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

The description names a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources. It also distinguishes itself from open-web search and from sibling ask_pipeworx, making its role 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?

It explicitly states when to use the tool (broad/multi-part questions over structured data) and when to use ask_pipeworx instead (single lookups, or not signed in). It also names the paid-tier constraint for thorough depth, giving clear routing 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?

Descriptions adds that results include 'names, descriptions, and full input schemas...ready to call directly, no second schema lookup needed', which complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

Front-loaded with main purpose and usage guidance. The list of domains is lengthy but necessary to convey the tool's broad applicability. Minor redundancy ('top-N...', 'each result is ready to call') could be streamlined.

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, when to use, behavioral traits, and parameter semantics adequately. Lacks details on return format but compensates by stating results include schemas and are callable directly, which is sufficient given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description explicitly lists aliases for query (task, q, description, search) and mentions limit, adding value beyond the schema's parameter 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 explicitly states 'Find tools by describing the data or task' and provides extensive domain examples (SEC filings, FDA drugs, etc.), making the purpose concrete and distinct from 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 advises 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance. Does not explicitly state when not to use, but the 'FIRST' implication provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond those by revealing parallel fan-out behavior, soft-failures (USPTO PatentsView sunset), fallback chains (GDELT→GNews), expected-empty sections for FDA products, and the semantics of sources_used/sources_failed. This gives an agent an accurate model of how the tool behaves in the real world.

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

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

The description is long, but every clause earns its place by defining a result section, a failure mode, or an input rule. It front-loads the usage trigger and the ALWAYS-PREFER directive before enumerating sources. The enumeration is dense but well-structured; a little more paragraphing would help, but there is 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?

With no output schema, the description carries the full burden of stating what the tool returns, and it does so comprehensively: each named output field (cik, resolved_from/to, recent_filings, fundamentals, patents, contracts, fda_products, hiring, news, LEI, sources_used/failed). It even covers edge cases like private companies and empty FDA sections. Nothing an agent needs to call or interpret the tool 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 schema coverage is 100%, the description adds meaning beyond the schema: it clarifies that type='company' and type='ticker' are interchangeable, that value accepts three distinct shapes, that names resolve via SEC EDGAR, and that zero-padding matters for CIKs. The schema only documents the parameter names; the description explains how to actually populate them.

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?

Purpose is immediately clear: one parallel call produces a comprehensive multi-source profile of a US public company. The trigger-phrase examples ('Tell me about X', 'research Acme', 'brief me on Tesla') make it obvious which user intents map to this tool, and the 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' sentence sharply distinguishes it from narrower retrieval 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 explicitly says to prefer this tool over chaining single-source lookups for holistic company questions, and it spells out accepted input forms (ticker, CIK, name). It also tells the agent how to recognize out-of-scope cases like private companies ('resolved:false') so the tool is not misused. This is outstanding when-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context on usage scenarios (e.g., stale context, clear sensitive data) but does not clarify idempotency behavior. 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?

Three sentences: core action, usage guidance, and related tools. Every sentence adds value with no redundancy.

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

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

The tool has a single parameter and no return schema. The description covers purpose, when to use, and related tools, fully sufficient for its simplicity.

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

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

Schema coverage is 100%, so the schema already describes the 'key' parameter. The description provides no additional meaning beyond 'by key,' meeting the baseline of 3.

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

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

The description clearly states the action 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by implication of pairing.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also provides guidance on pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds procedural context: fetches the page, extracts title/description/key links, and outputs standard markdown format. This goes beyond annotations without contradicting them, earning a 4.

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

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

The description is concise with three sentences: purpose/benefit, process, use cases. It's front-loaded and each sentence adds value without redundancy.

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

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

Given the parameter count (2), full schema coverage, and lack of output schema, the description sufficiently explains the output format (single text blob, markdown, ready to drop) and use. Annotations cover safety and idempotency. The AI agent has all needed context to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add new semantic information about parameters beyond what the schema provides (e.g., url format, max_links default/max). It reiterates the extraction process but doesn't clarify parameter behavior further.

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: generating a production-ready llms.txt file for any URL. It specifies the resource (llms.txt for a URL) and the action (generate). It also distinguishes it from sibling tools by mentioning specific use cases like indexing for AI crawlers, which no sibling tool addresses.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor's AI presence. While it doesn't mention when not to use or compare to siblings, the sibling list shows no overlap, making the context clear. A score of 4 reflects this clarity without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the output structure, which aids understanding of tool behavior. No contradictions; behavioral disclosure is sufficient given the annotations.

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

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

The description is a single, well-structured sentence that front-loads the core action and then lists return fields. No superfluous text; every word adds value.

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

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

With an output schema present (implied by context signal), the description does not need to explain return values in depth, but it does so briefly. Full input specification and clear output description make it complete for a simple tool.

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

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

Schema coverage is 100% and includes a description and examples for the DOI parameter. The tool description adds minimal extra meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool's function: fetch open-access status and the best free legal copy given a DOI. It specifies the inputs (DOI) and outputs (is_oa, oa_status, best location, journal metadata), distinguishing it from sibling tools like search_papers.

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 the input (DOI) and what it does, so usage context is clear. However, it does not provide explicit guidance on when not to use it or compare to alternatives, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds value by listing returned fields (id, type, etc.) and confirming read-only behavior.

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

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

Two informative sentences with zero fluff, front-loaded action and returned fields, then usage guidance. Every sentence earns its place.

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

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

Despite no output schema, the description enumerates return fields. For a simple list tool with one parameter and strong annotations, the description is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with a clear description for include_inactive. The tool description reinforces that the parameter controls inclusion of cancelled subscriptions, but doesn't significantly enhance 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 it lists the caller's active subscriptions, specifying the verb (list), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Despite annotations being all false (minimal signal), the description thoroughly discloses behavioral traits: filing without an account returns a claim_token, rate limit of 5 per day, free usage with no quota impact, and daily human review. This goes well beyond the annotations and gives the agent clear expectations for side effects and limitations.

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

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

The description is longer than typical but every sentence carries useful information: purpose, use cases, exclusions, token workflow, and limits. It is front-loaded with the core purpose and follows a logical progression. Slightly verbose, but the density of relevant facts justifies the 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?

With no output schema, the description covers return behavior well by explaining the claim_token flow (initial filing and later status check) and mentions rate limits. However, it leaves minor ambiguity about what happens when an account is present (vs. token-based response) and does not detail the response format for resolved reports. Still, it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100% with detailed descriptions for all 4 parameters, so the baseline is 3. The description adds minor extra context (e.g., how to reuse claim_token, that filing without an account returns the token) but largely reinforces schema content. It does not substantially improve 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 opens with a specific verb phrase 'Tell the Pipeworx team' and enumerates exact use cases (bug, feature/data_gap, praise). It explicitly distinguishes this tool from siblings by restricting to Pipeworx-served tools and excluding other MCP servers' tools, eliminating ambiguity about scope.

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

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

Provides explicit 'Use when' conditions (wrong/stale data, missing tool, praise) and a clear 'when not to use' (different MCP server) with reasoning. Also includes actionable guidance on how to phrase feedback (focus on Pipeworx tools/packs) and explains the claim_token follow-up workflow, making it easy for an agent to decide and invoke correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds value beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides data source, privacy, and caching behavior.

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

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

The description is two concise sentences plus a bulleted list of use cases. Every sentence is informative, front-loaded with purpose, and 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 tool has 1 optional parameter, no output schema, and annotations cover safety. Description covers behavior, data source, privacy, caching, and use cases, making it fully informative for an agent to invoke correctly.

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

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

Schema coverage is 100% for the single parameter 'window' with enum and description. Description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds comparative guidance 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 that the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It distinguishes itself from siblings by focusing on trending data from other AI agents, and provides three specific use cases.

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

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

The description provides explicit when-to-use guidance with three bullet points (discovering hot data sources, confirming canonical choice, seeing use case alignment). It does not mention when not to use or alternatives among siblings, but gives context for window length selection.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details behavioral traits: monotonicity checks, partition sum checks, semantic similarity threshold (≥0.30 Jaccard), partition filter (placeholders), and fill check against live CLOB depth. 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 detailed and structurally sound: starts with overview, then explains modes, then fills in specifics like semantic anchor, partition filter, fill check. Every sentence provides value, though it is relatively long; could be slightly more concise but still effective.

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?

Completeness is high: explains response format (opportunities[], partition_check, fill_check), contextualizes with sibling tools (polymarket_fill_risk), and covers all key behaviors. No output schema but description adequately explains return values.

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 are 100% covered, but the description adds substantial meaning: explains that event expects a Polymarket event slug (or full URL), topic expects a seed question, and details the different behavior modes and constraints (e.g., semantic anchor, partition filter).

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 via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, and references sibling tools for related 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 explains when to call with no args (trending scan), when to use event (specific market), and when to use topic (cross-event scanning). Provides guidance on when not to trade (realizable_edge_pp ≤ 0) and mentions custom sizing via polymarket_fill_risk.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant transparency by detailing caching behavior ('Cached 1h at the KV level'), the internal model families and their parameters, and the structure of the response including diagnostics for empty segments. This exceeds the minimum expected from 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 but becomes dense and lengthy with technical details about model families and edge cases. While comprehensive, it could be more streamlined by separating high-level usage from algorithmic specifics. The structure is logical but verbose.

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

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

Given the complexity (9 parameters, multiple segments, no output schema), the description thoroughly explains the response structure, edge cases (empty segments, Fed bets), and the meaning of key result fields (edge_pp_net, kelly_fraction, etc.). It covers why segments might be empty and includes caching details, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions the knobs at a high level (e.g., min_liquidity, max_spread_pp) but does not add substantial per-parameter meaning beyond the schema descriptions. It provides context for how knobs work together but not extra detail on individual parameters.

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

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

The description clearly states the verb ('Scan top Polymarket markets and return opportunities') and the resource ('where Pipeworx data disagrees with market price'). It specifies the intended use case ('what should I bet on today') and distinguishes the tool from siblings like polymarket_arbitrage by emphasizing the data disagreement approach.

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

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

The description implies usage for daily bet discovery but does not explicitly state when not to use this tool or compare it to alternatives such as polymarket_arbitrage or polymarket_edge_tracker. The context is clear but lacks exclusions or direct comparisons.

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 as true and destructiveHint as false. The description adds valuable behavioral context: history bounded by 60-day TTL, decay computed from daily closes (not intraday), and details on computed fields like trend and decay_pp_per_day. 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 well-structured: opening purpose, then detailed response fields, then limitations. While somewhat long, every sentence adds value and the bullet-like format for RESPONSE improves readability. It could be slightly more concise, but overall effective.

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

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

No output schema exists, so the description must fully explain return values. It does so comprehensively: tracked array with full time-series, first_seen, trend, decay; expired array with lifespan_days; snapshot_dates. It also explains data source (cache-miss driven), limits (TTL, snapshot start), and scaling of decay. Complete for a time-series analytical 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% for the two parameters. The description adds context beyond schema: explains 'days' default/clamping (though schema says clamp 2-30, description says max 30) and describes 'window' as snapshot family. This extra clarification merits a 4.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tool polymarket_edges (which likely provides current snapshots) by focusing on historical tracking and trend computation.

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 context for when this tool is relevant (e.g., distinguishing fresh vs old edges) and explains the meaning of response fields (tracked, expired, snapshot_dates). It does not explicitly state when not to use it or mention alternatives, but the guidance on interpretation is sufficient for typical use.

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

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

Despite annotations declaring readOnlyHint=true, the description adds rich behavioral context: walks the ladder, returns a verdict (clean|degraded|cannot_fill), warns about forced_directional_risk and the danger of partial fills. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for modes and a list of return fields. Every sentence adds value, though some minor redundancy could be trimmed. Still, it is efficient for the complexity.

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

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

Without an output schema, the description comprehensively lists all return fields and explains their meaning. It covers edge cases (thin_legs, forced_directional_risk) and provides the verdict logic. This gives the agent sufficient information to decide and interpret results.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds extra semantics: clarifies interpretation of size_usd for single-market vs basket, default side logic for basket, and clamps. This goes beyond the schema, raising the value.

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

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

Explicitly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. Clearly distinguishes two modes (single-market and basket) and provides the return fields. Directly references sibling tools (polymarket_arbitrage, polymarket_edges) to indicate when to use this 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Gives strong rationale: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position (dominant loss mode).

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by disclosing critical behavioral caveats: pairing is based on keyword overlap rather than a shared resolution source, `pairing_unverified` is always set when pairs are returned, spreads are gross and do not model Kalshi fees, unknown legs are never paired, and a null `temporal_alignment` means 'could not be computed,' not 'aligned.' This is exemplary transparency for a tool with subtle failure modes.

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

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

The description is long and dense, but it is front-loaded with the core purpose and organized around clear sections: modes, response shape, safety fields, flags, skipped categories, and fee disclosure. Nearly every sentence adds a distinct fact needed for correct interpretation. It could be trimmed slightly, and repeated phrases like 'in EITHER mode' appear more than once, but the length is largely justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, `top_spreads_pp`, `compatibility_warning`, `compatibility_codes[]`, per-entry flags, skipped counters, `temporal_alignment`, and `fees_note` are all described. The only meaningful gap is the missing statement about whether a call requires at least one mode parameter and what happens with an empty argument set.

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

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

Schema description coverage is 100%, so the schema already documents `topic`, `kalshi_event_ticker`, and `polymarket_event_slug`. The description adds meaning beyond the schema by defining the two modes, explaining that the explicit fields override the topic-mapped side, and clarifying that both modes run the identical token-overlap matcher with the same disclosures. A small gap remains: it never says what happens if no parameters are supplied, given that all three are optional.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by its cross-venue, same-question scope, and it names two concrete invocation modes. An agent can immediately tell what this tool computes and how it differs from near-neighbors.

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

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

The description gives clear within-tool selection guidance: use `topic` shortcuts for pre-mapped macro events, or explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and notes that both modes run the identical matcher. It also warns that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable.' However, it never explicitly states when to choose this tool over sibling alternatives such as polymarket_arbitrage or polymarket_edges.

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, destructiveHint, idempotentHint. Description adds scope (identifier-based) and pairing context, 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, front-loaded with action, every sentence adds value. No waste.

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

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

Simple tool with one optional param, description covers purpose, usage, scope, and pairing. No output schema but return value is implicit.

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 100%, but description adds meaning by explaining dual behavior of key parameter (retrieve vs list).

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

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

Description clearly states it retrieves a value saved via remember or lists all keys, with concrete examples like ticker, address, notes. Distinguishes from siblings remember and forget.

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

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

Explicitly describes when to use (look up context) and when to omit key (list all). Mentions pairing with remember/forget, though does not explicitly state when not to use.

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

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

The description states that setting mark_read:true flags returned events as read, implying a write side effect. However, annotations include readOnlyHint=true, which indicates no write operations. This contradiction severely undermines transparency.

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 four sentences, each adding essential information—purpose, return fields, parameter usage, and alternative access. No redundant or filler content; efficiently front-loaded with the main action.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, raw payload) and parameter usage. It covers common use cases like filtering and pagination limits, but lacks mention of error conditions or authentication requirements, leaving minor gaps.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining each parameter in context (e.g., 'Filter by type (e.g. "sec_8k")', 'ISO timestamp', 'set mark_read:true to flag returned events read') and providing usage rationale, exceeding the schema alone.

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

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

The description states a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly identifying the tool's function. It distinguishes itself by specifying return fields and filtering options, though no direct sibling differentiation is provided; however, the purpose is unambiguous.

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

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

The description mentions that polling works fine and provides an alternative access method (GET registry.pipeworx.io/alerts.json), but does not explicitly state when to use this tool versus sibling tools or exclude unsuitable contexts. The guidance is present but not comprehensive.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds details on data sources (SEC, GDELT/GNews, USPTO), failure modes (GDELT rate-limited, PatentsView sunset), and return structure. 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 front-loaded with examples and use cases. It is detailed but every sentence serves a purpose. Slightly longer than necessary for a concise description, but still effective.

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 rich annotations, complete schema coverage, and detailed description covering sources, failure modes, and return structure, the description is fully complete for an agent to understand and 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%. Description adds meaning by explaining accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d'), 'value' (ticker or zero-padded CIK), and enum for 'type'. Provides example usage 'AAPL' and '0000320193'.

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: 'change feed for a company in the last N days/weeks/months' with concrete examples like 'What's new with X' and 'latest on Y'. It explicitly distinguishes from the sibling tool entity_profile.

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

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

Provides explicit guidance: 'Use entity_profile instead when you want the static profile...' and explains the tool fans out to multiple sources. The context signals and sibling list confirm this is well-differentiated.

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 idempotentHint=true and destructiveHint=false. The description adds scoping by identifier and persistence duration (permanent vs 24h), which are valuable beyond annotations. Could mention overwriting behavior, but overall good.

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, front-loaded with purpose, every sentence adds value. No wasted words. Excellent for quick comprehension.

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

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

Given the tool's simplicity (two params, no output schema), the description covers purpose, usage, behavior, and companion tools thoroughly. No gaps 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 covers both parameters with examples. Description adds context about key-value nature and scoping, enhancing understanding beyond the schema. No missing 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 clearly states the tool saves data for later reuse, with specific examples like ticker, address, preference. It distinguishes from siblings by naming recall and forget, making the purpose explicit 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?

Explicitly states when to use (discover something worth carrying forward) and pairs with recall and forget. Provides clear context for the agent to decide when to invoke this tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-match behavior (asserts nothing, returns `figi_candidates`), and explicit listing of unresolved identifiers under `unresolved`. It also reveals internal cascading through multiple endpoints, which explains why the call may take time.

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 information-rich, but it is a long run-on with deep parenthetical nesting (e.g., the company type paragraph). It is front-loaded with examples and the core directive, yet the structure could be improved with clearer separation between the two types. Every sentence adds value, but readability suffers.

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 does a strong job of naming return fields and behaviors: CIK, ticker, company_name, LEI, FIGI, figi_candidates, unresolved, RxCUI, ingredient, brand, and a citation. It explains both input and output semantics per type, covers edge cases, and notes degradation, leaving little that an agent needs to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description substantially enriches both parameters: it documents accepted input forms (ticker, CIK, ISIN, or company name) and gives specific examples ('ozempic', 'CH0038863350'). It adds crucial disambiguation rules for bonds, such as passing the issuer exactly as printed and never the full noun phrase.

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

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

The description opens with concrete example queries ('What's the ticker for…', 'find the CIK for…') and states the core operation: resolving a user-spoken NAME to the canonical/official identifiers other tools require as input. It identifies the exact resource (identifiers: CIK, LEI, FIGI, RxCUI) and supports two explicit entity types, 'company' and 'drug'.

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 instructs 'Use FIRST whenever you have a name but need an ID', giving a clear trigger condition. It also restricts the `value` parameter to the entity name only and warns against trailing security-class words, which orients the agent to the correct input discipline. It does not name sibling tools to avoid, but the 'first' directive plus the enrichment notes make the use case unambiguous.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds: 'Probes each entity with ai_visibility_check, ranks by score, surfaces most/least, returns ranked list with score, confidence, signal density.' This fully discloses the process and output beyond annotations.

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

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

Two sentences: first is action-oriented and front-loaded, second adds context and output format. Every word adds value without redundancy.

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

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

Given 4 well-documented parameters, no nested objects, and annotations covering safety, the description explains the composite behavior and output format sufficiently despite lacking an output schema.

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

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

Schema coverage is 100% with descriptions. Description adds crucial nuance: 'First entry treated as the subject for narrative; rest are competitors.' Also explains model options: 'workers-ai (free default), anthropic (requires _apiKey)'. This supplements 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 starts with 'Compare AI visibility across multiple entities side-by-side', clearly stating the action and resource. It differentiates from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (generic) by specifying the process of probing with ai_visibility_check and ranking.

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 use case: 'Useful for competitive AI-marketing audits'. Provides an example question. However, it does not explicitly mention when not to use or alternatives beyond the implicit difference from 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list. No contradiction with annotations.

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

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

The description is a single dense paragraph, informative but somewhat packed. It effectively uses front-loading but could benefit from bullet points for readability. Still concise and to the point.

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

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

Given no output schema, the description fully covers return values (summary block fields, per-advisory detail, links, alternative versions). It also explains partial failure behavior, timing caveats, and ecosystem limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so parameters are well-documented in schema. The description adds minor nuance (scoped packages accepted, default version behavior) but does not significantly extend schema 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 clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia data to answer whether to add a package. It uses specific verbs like 'scan' and 'checks', and distinguishes from siblings by focusing on npm dependency evaluation.

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: when an agent asks about safety, popularity, or size of an npm package. It also clearly scopes to NPM ecosystem and directs other ecosystems to deps.dev:version, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description focuses on disclosing key behaviors: pagination ('Returns up to 50 results per page') and optional filtering ('restrict to OA-only'). These add value beyond annotations without contradiction. A score of 4 reflects good supplementary behavioral info.

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 extremely concise: two sentences, front-loaded with the key action, then optionality and result limit. Every sentence contributes essential information without 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 (3 parameters, straightforward search) and the existence of an output schema (so return values need not be explained), the description covers the main points: search scope, optionality, and page size. It misses ordering or default sort, but for a search tool this is acceptable. Hence 4.

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 description adds little beyond the input schema, which already fully documents all three parameters (100% coverage). While it echoes the OA restriction, it does not enrich understanding of parameter format or constraints. According to the rule, baseline 3 is appropriate when schema coverage is high.

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 ('keyword search'), resource ('scholarly papers via Unpaywall'), and scope (optional OA restriction, pagination). It effectively distinguishes from siblings by specifying 'scholarly papers' and 'Unpaywall's coverage', making its domain unique among similar tools like search_within or deep_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 implies usage for keyword search on scholarly papers but does not explicitly tell when to use this tool versus alternatives like deep_research or search_within. It provides context (e.g., OA filter, 50 results per page) but lacks exclusions or direct comparisons, so it scores at the 'implied usage' level.

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, and non-destructive behavior. The description adds highly valuable behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and offset-bearing passages. 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 concise and well-structured. It starts with the core purpose, then details usage context, pairing suggestions, technical specifics, and constraints. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description clearly outlines return values (top-N passages with offsets and scores). All relevant aspects—input size limits, embedding model, windowing, pairing with sibling, and output details—are covered, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description enriches parameter understanding: explains 'text' as the document to search, provides natural-language examples for 'query', and clarifies 'limit' as max passages (1-20, default 5). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with character offsets and similarity scores. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded, making the purpose unambiguous.

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

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

Explicitly tells when to use: when the record is too big to fit in the prompt. Also provides an alternative workflow (pair with ask_pipeworx_grounded) and explains benefits like saving context and offset-based verification.

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

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

Description adds significant behavioral context beyond annotations: creation of subscription, return of ID, delivery channel details, phone verification requirement, and rate limits. 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?

Description is detailed but not overly verbose. Key information is front-loaded; however, some sections (e.g., delivery details) could be slightly trimmed without losing clarity.

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

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

For a complex tool with 3 parameters (including nested objects) and no output schema, the description covers all essential aspects: subscription types, parameter formats, delivery channels, authentication, and limitations. No missing information.

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

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

Schema coverage is 100%, and description enriches each parameter with concrete examples and use-case-specific details (e.g., item codes for sec_8k, topic for polymarket_edge). Delivers meaning beyond the schema.

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

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

Description clearly states it creates a proactive monitoring subscription to a live-data event stream, distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit context for when to use (setting up monitoring), required account type, and lists supported types. Lacks explicit 'when not to use' but is otherwise very 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. The description adds behavioral details: it returns dynamic example questions drawn from a live catalog, explains the no-argument full spread vs topic-focused call, and notes it's an onboarding entry point—no side effects are implied.

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 lengthy but well-structured: common questions front-loaded, followed by explanation of output and usage. Every sentence adds value, though slightly verbose for a simple tool.

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

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

Despite no output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shape) and how to invoke. It also places the tool in the broader context of onboarding, making it complete for its purpose.

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

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

Schema coverage is 100% with one optional 'topic' parameter described with examples. The description adds value by stating omission gives a cross-category spread and listing example values. Sufficient but straightforward.

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 as an onboarding entry point, listing common user intents (e.g., 'What can I ask Pipeworx?') and specifying it returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings by advising to use this first when the agent doesn't know Pipeworx's capabilities.

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 guides use 'when you do not yet know what Pipeworx can do for you' and suggests passing an optional topic to focus. It also references meta-tools to learn how to call them, providing clear when-to-use 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 declare idempotentHint true and destructiveHint false; the description adds valuable context that the row is deactivated not deleted, and that historical events remain available via recent_alerts. This goes beyond what annotations provide.

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

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

The description is extremely concise: two sentences, no wasted words. The first sentence immediately states the action and key constraint, and the second provides important behavioral nuance. Perfectly front-loaded.

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

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

For a simple cancellation tool with one parameter and no output schema, the description covers the essential behavioral outcomes (ownership check, deactivation, historical data availability) and even cross-references another tool (recent_alerts). Minor gaps: no mention of error cases or return value, but these are not critical given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds the context of ownership enforcement but does not elaborate further on the parameter's format or constraints beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing the tool's action. It also adds nuance about ownership enforcement and the deactivation effect, setting it apart from related tools like list_subscriptions or 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?

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear when-to-use context. However, it does not explicitly mention when not to use it or suggest alternatives like a hard-delete tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses significant behavioral traits: the dual-pipeline routing, the specific verdict set, and the critical caveat that 'could_not_verify means the check did not happen… it is NOT evidence for or against the claim.' It also explains the distinction between unsupported and could_not_verify and notes the efficiency gain over 4-6 sequential calls.

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

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

Although the description is longer than the calibration high example, every sentence contributes essential information: definition, usage, routing, output, caveats, and efficiency. It is well-structured and front-loaded, starting with concrete examples and ending with a concise summary of the pipeline it replaces.

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

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

The description is complete for a complex tool. It covers the main use case, the special handling for financial claims, the full set of possible verdicts, the meaning of error-related verdicts, and the practical benefit of replacing multiple calls. No output schema exists, but the description adequately describes return values and reasoning, making it self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value for tolerance_pct by explaining how it overrides the implicit tolerance and recommending 1-2 for hallucination detection, which provides guidance beyond the schema description for the parameter.

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

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

The description clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It provides concrete invocation examples ('Is it true that…', 'fact check') and distinguishes itself as an integrated pipeline that replaces multiple sequential calls, making it distinct from sibling tools like ask_pipeworx.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two execution paths (SEC EDGAR for company-financial claims, grounded pipeline for others), giving clear context. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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