Blockscout

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

Goes beyond annotations by detailing the default model (Workers AI, free), optional Anthropic probing with BYO key, and the scoring range (0-100). 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?

Single paragraph, front-loaded with action and key details, every sentence earns its place. Efficient and clear.

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

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

No output schema, but description adequately explains return structure (per-model {score, confidence, signals, raw_response} + combined view). Covers all necessary information for a tool of this complexity.

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

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

Schema has 100% coverage, but description adds practical details: 'Omit for just workers-ai' for models, 'only needed if anthropic is in models' for _apiKey, and context helps disambiguate.

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 ('probe') and resource ('LLMs for knowledge about an entity'), clearly distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring across models.

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 cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context about default vs paid models, but does not explicitly list when NOT to use or alternatives.

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

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

Annotations already disclose readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it routes to a massive pool of tools, returns citations, works on every tier, and is described as 'one fast call.' It does not contradict annotations, and provides behavioral details like handling breaking news via live news feeds.

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

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

The description is dense but well-structured, with a clear opening directive, examples, and a step-up section. It is longer than the minimal ideal, but every sentence adds information (triggers, examples, alternatives, scope). It earns a 4 rather than 5 due to slight redundancy (e.g., multiple 'use whenever' clauses) that could be tightened.

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 tool with no output schema, the description explains what is returned (structured answer with citation URIs) and how to use it effectively. It covers the tool's scope (broad real-world data), limitations, and when to use alternatives. The examples cover diverse use cases, making the tool's behavior clear even without a schema.

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

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

Schema description coverage is 100%: all six parameters (question and five aliases) are documented in the input schema. The description itself does not add extra parameter meaning beyond restating that 'query, q, prompt, text, input' are aliases, which is already in the schema. Thus, the baseline of 3 applies.

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

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

The description clearly states the tool's function: it answers factual questions by routing to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It uses a specific verb ('ask') and resource ('Pipeworx'), and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by stating when to use each.

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

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

Usage guidance is explicit and prominent: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It provides concrete trigger phrases ('what is', 'look up', 'find', etc.) and examples, then tells when to step up to alternatives ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research').

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 convey read-only, open-world, and idempotent characteristics. The description adds valuable context about live candidate testing, retirement of candidates, and reassurance that it's a fully working router ('Falls back to nothing — this IS a full working router'). It does not contradict annotations and enriches the behavioral profile.

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

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

The description is a single paragraph that front-loads the key point ('Beta version of ask_pipeworx') and then efficiently covers current status, usage, and reassurance. Each sentence earns its place, though there is slight redundancy in stating same tools/arguments twice.

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

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

Given the tool's complexity and no output schema, the description sufficiently explains the experimental nature, current equivalence to the stable router, and what to expect (same response shape). It references the stable version for response details, which is acceptable given sibling context. It could be more explicit about return structure, but the reference to ask_pipeworx covers this.

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

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

Input schema covers 100% of parameters with descriptions, including aliases. The description only states 'same arguments' as ask_pipeworx, adding no parameter-level details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx while specifying the exact scope (same 5,529 tools, arguments, response shape).

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: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate) and that results are compared to the stable router. It doesn't explicitly list exclusions but provides clear context for choosing this over the stable variant.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the structured response format with refusal_reason enum, the one-extra-LLM-call overhead, and that it only uses tool-result content. It also explicitly states that refusal occurs when data doesn't directly answer, which is not inferable from annotations alone.

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

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

The description is compact but dense, starting with a clear purpose and then covering mechanism, output, use cases, and trade-off in four sentences. No filler language is present, though it's longer than minimal descriptions due to 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?

Despite lacking an output schema, the description fully specifies the return object and all possible refusal reasons. Combined with the annotations, it gives an agent all necessary context to decide when to invoke this tool and what to expect.

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

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

The schema already covers all parameters with 100% description coverage, including their alias relationship. The description adds no additional parameter-level information, so it stays at 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 tool's function: a hallucination-resistant answer mode that extracts answers only from tool results, with evidence and refusal. It explicitly contrasts with the sibling tool ask_pipeworx, making its purpose distinguishable.

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 ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'). It also names the alternative tool and notes the extra LLM call cost, providing clear decision guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds extensive behavioral detail: resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence short-circuits, closed market handling), and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long and detailed, well-structured with sections, but it is verbose. Could be more concise without losing essential information. Every sentence earns its place, but overall length detracts from 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 complexity of the tool (multiple response shapes, classification, fan-out, safety mechanisms, and no output schema), the description is extremely thorough. It covers return fields, edge cases, and behavioral details comprehensively.

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

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

Schema description coverage is 100%, so each parameter already has a description. The description adds context beyond the schema, e.g., examples for 'market' and explanation of 'depth' and 'include_raw' behavior. It adds value but does not fundamentally compensate for gaps.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output, and gives use-case examples like 'should I bet on X'. This distinguishes it from sibling tools like polymarket_edges, though no explicit differentiation is given.

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

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

Provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also gives fan-out examples per category. However, it does not explicitly mention when not to use or alternative tools, though the context is clear.

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

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

The description adds significant context beyond annotations: it explains data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the inclusion of citation URIs. Annotations already indicate read-only and idempotent, so the description enriches 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 concise yet comprehensive, starting with example queries and clearly explaining behavior. Every sentence serves a purpose, and the structure efficiently conveys key information without redundancy.

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

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

Given no output schema, the description adequately explains the return format (paired data + citation URIs) and the sorting behavior. It also mentions the replacement of 8–15 sequential lookups, giving the agent confidence in efficiency. For the complexity of this tool, the description is complete.

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

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

While the schema already has 100% coverage and describes parameters, the description adds meaningful context: for type='company' it specifies data pulled (revenue, net income, etc.) and for type='drug' it specifies adverse-event counts. It also explains how values are interpreted (tickers/CIKs for companies, names for drugs), going beyond the schema's brief 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 does side-by-side comparison of 2–5 companies or drugs, and provides example queries ('X vs Y', 'which is bigger'). It distinguishes itself from sequential single-pack lookups, 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 advises 'ALWAYS PREFER over sequential single-pack lookups' and gives example use cases. This provides strong guidance on when to use the tool and when not to use alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true) by disclosing key behaviors: it never invents answers and returns explicit gaps[], includes stable pipeworx:// citations only when fetchable, returns contradictions[] for standard/thorough depths, semantically excerpts large records, and has documented latency ranges. This enriches the safety and usage profile without contradicting the annotations.

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

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

The description is long but information-dense, with a logical flow: account requirements first, then core function, usage guidance, depth behavior, and output/performance details. Every sentence adds value for a complex tool, but some sections (e.g., the detailed citation_uri explanation) could be tightened without losing essential context.

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 thoroughly explains return values: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', gaps[], contradictions[], hop field, and citation_uri properties. It also covers account limitations, latency, and limitations with open-news topics, making it complete for a complex research 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% with detailed descriptions for both params (depth enum and question). The description adds some context, such as examples of appropriate questions and how depth maps to hop behavior, but most parameter meaning is already in the schema. It doesn't materially extend the semantic understanding beyond what the schema provides, so the 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 purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It also distinguishes itself from siblings by explicitly stating 'this is NOT open-web search' and detailing how it decomposes questions and returns a findings packet, making it distinct from ask_pipeworx and other search 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 provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives account prerequisite and alternative if not signed in, plus depth-level recommendations and latency expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the tool returns top-N relevant tools with schemas and examples, and that results are ready to call directly. This is useful but does not disclose any additional behavioral traits like rate limits or auth needs.

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

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

The description is somewhat long due to listing many example domains, but it is front-loaded with the core purpose. Each sentence adds value, though it could be more concise.

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

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

Despite no output schema, the description adequately explains what the tool returns: top-N tools with names, descriptions, and full input schemas with examples. This is sufficient for the agent to understand the return format and use the results directly.

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

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

Schema coverage is 100% with all parameters described. The description mentions the limit parameter and that results are top-N, but adds minimal extra meaning beyond the schema. Baseline is 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 that the tool finds tools by describing a data or task, and provides a long list of example domains (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by advising to call it first to see the option set.

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 this tool when browsing, searching, or discovering what tools exist, and to call it FIRST when many tools are available. This provides clear guidance on when to use it over 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 safe, read-only, idempotent behavior. Description adds details on data sources (SEC EDGAR, XBRL, USPTO, etc.) and limitations (e.g., patents API sunset in May 2025). No contradiction.

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

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

Front-loaded with example queries, well-structured with clear sections. Slightly dense but every sentence adds value. Could be marginally more concise.

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

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

Despite no output schema, description details returned fields (cik, filings, fundamentals, patents, news, LEI) and mentions the patents limitation. Lacks error handling details but is sufficient for the tool's 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%, so baseline 3. Description adds clarity by explaining that type is only 'company' and value must be ticker or CIK, not names, and recommends resolve_entity. This adds value beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives example queries. It distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly says to prefer this tool over chaining single-pack lookups for holistic views, and instructs to use resolve_entity if only a name is available. Provides clear when-to-use and when-not-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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and that memory was stored earlier, which is useful but not critical 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 with no wasted words. Front-loaded with action and resource, then usage guidance. Highly concise and structured.

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

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

For a tool with a single parameter, no output schema, and annotations present, the description is complete: it covers purpose, usage, and pairing with siblings.

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

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

Schema coverage is 100% with description 'Memory key to delete'. The description does not add additional 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 verb 'Delete', the resource 'previously stored memory', and specifies the action by key. It differentiates from siblings like 'remember' and 'recall' by mentioning 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 provides when to use: 'context is stale, task is done, clear sensitive data'. Also suggests pairing with 'remember' and 'recall' for context on 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?

Describes the process: fetches page, extracts title/description/key links, emits standard markdown. Adds behavioral context beyond annotations (read-only, idempotent) but does not cover edge cases like large pages or errors.

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

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

Two sentences plus a bullet list; purpose is front-loaded. No extraneous content, but slightly unstructured.

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 input, process, and output format. Lacks details on error handling, timeouts, or redirects, but for a simple 2-param tool with annotations, it is fairly complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats parameter names but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt', and the scope 'for any URL'. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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

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

Explicitly lists use cases (client site indexing, own project drafting, competitor audit) but does not provide exclusions or comparisons to alternatives like scan_competitor_ai_presence.

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

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

Annotations already provide safety and idempotency hints. The description adds value by specifying the supported chains (Ethereum, Optimism, etc.) and the exact data returned (balance, tx count, token stats). It does not contradict any 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 fairly long due to listing many chain names and example queries. While it starts with useful examples, the extensive list could be shortened or summarized. It earns its place but could be more concise.

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

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

The tool has only two parameters and an output schema exists (implied). The description covers purpose, parameters, and return types. It does not mention limitations like rate limits, but for a simple read-only tool, this is adequate.

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

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

Schema coverage is 100%, and the description reinforces that 'chain' is a slug (referencing list_chains) and 'address' is a 0x address. It provides concrete examples of valid chain values and addresses, adding helpful context beyond the schema's brief description.

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

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

The description clearly states the tool returns an on-chain address summary across 20+ EVM chains, including balance, transaction count, and token-holding stats. It provides example queries that illustrate the purpose, and distinguishes it from sibling tools like get_address_token_transfers and get_address_txns by focusing on a summary rather than specific transfers or transactions.

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 instructs to pass a chain slug and 0x address, and gives examples of when to use the tool (e.g., 'What's the balance of [wallet]'). It implicitly differentiates from siblings by listing the returned data, but does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds context by specifying the types of transfers (ERC-20/721/1155) and use cases. 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 paragraph that alternates between query examples and purpose. 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?

Given the output schema exists, the tool is fully covered: parameters explained, use cases given, annotations provide safety, and the description is sufficient 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 50% (only limit and token have descriptions). The description compensates by explaining the overall purpose and mentioning the token filter, but does not describe chain or address. However, those parameters are self-explanatory and examples clarify usage.

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

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

The description uses specific verbs ('token transfers / NFT activity', 'tracing') and clearly identifies the resource as token transfer logs for an EVM address. It distinguishes from sibling tools like get_address (general info) and get_address_txns (transactions) by focusing exclusively on token transfers.

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 context for usage ('tracing NFT activity, stablecoin flows, airdrops') and mentions the token filter. It does not explicitly state when not to use or compare to alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it returns 'recent transactions' and specifies 'EVM address,' which aids understanding. 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, front-loaded with natural language use cases, and uses clear structure with slash-separated examples. Every sentence adds value without repetition.

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 presence of an output schema (not shown but context indicates it exists), the description focuses on usage and parameters appropriately. It covers key aspects but does not detail error handling or edge cases, which is acceptable for this 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 50%: limit and filter have descriptions, chain and address do not. The description compensates by stating 'Pass chain + 0x address,' clarifying that chain is the EVM chain and address is a 0x-prefixed address.

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

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

The description clearly states the tool retrieves recent transactions for an EVM address, using specific verb 'get' and resource 'address txns'. It distinguishes from siblings like get_address_token_transfers by focusing on all transactions, not just token transfers.

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 provides explicit instructions: 'Pass chain + 0x address; optionally filter by direction (to/from).' It also suggests use cases: 'wallet-activity audit, fund-flow tracing.' No explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds information about returned fields and use cases, enhancing transparency without contradiction.

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

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

The description is concise, front-loaded with example queries, and every sentence adds value. No extraneous information.

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

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

Given the tool's simplicity (2 parameters, no enums) and the presence of an output schema, the description covers core functionality and use cases. Minor omissions like error handling do not detract significantly.

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 0%, so the description must compensate. It mentions 'by number or hash' but does not elaborate on parameter formats or constraints. Examples in the schema help, but the description alone is insufficient for complete parameter understanding.

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

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

The description clearly states the tool retrieves block details by number or hash, lists returned fields (timestamp, gas used, etc.) and provides example queries. It distinguishes itself from sibling tools by focusing on block-level data.

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

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

The description includes example natural language queries that guide usage. It does not explicitly state when not to use this tool, but the context is clear enough for block retrieval tasks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by specifying the returned metadata fields (name, symbol, etc.) and the on-chain scope, providing useful detail beyond annotations without contradiction.

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

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

The description is concise, using example queries and a clear list of returned fields. Every sentence adds value, and the purpose is front-loaded, making it efficient for an AI agent to understand.

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 presence of an output schema (not shown), the description does not need to detail return values. It lists the key metadata fields and provides examples. It is complete for a simple token info tool, though it could mention supported chains or error handling briefly.

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 50%: the 'contract' parameter has a description, but 'chain' does not. The description does not explain the 'chain' parameter explicitly, though the example implies it is a blockchain identifier. This adds marginal value, but the description could better compensate for the missing schema documentation.

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

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

The description clearly states the tool returns token metadata including name, symbol, decimals, total supply, holder count, and contract type. It provides example queries and specifies the use case for on-chain token characterization, distinguishing it from sibling tools like get_address_token_transfers.

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

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

The description explicitly states 'Use for on-chain token characterization,' indicating when to use the tool. It does not provide explicit exclusions or alternatives, but the context is clear given the uniqueness of the tool among siblings.

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

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

Annotations already declare it read-only, idempotent, and non-destructive. The description adds value by specifying the rich output (decoded calldata, status, gas) and appropriate use contexts, with no contradictions to 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 highly concise: two focused sentences front-loaded with common query patterns, then explicit parameter requirements and use cases. Every phrase serves a purpose with 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?

Given the simplicity of the tool (two required scalar parameters) and presence of an output schema, the description covers purpose, input requirements, and typical use cases. It omits error handling or rate limits, but these are minor gaps for a straightforward look-up 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 0%, so the description must compensate. It mentions the two parameters ('chain + tx_hash') but does not define their format or allowed values (e.g., chain ID or name, hash length). The examples in the schema provide some guidance, but the description itself adds minimal semantics beyond naming the 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?

Description clearly states the tool retrieves full transaction details for a given hash, listing specific fields (from, to, value, method, status, gas, decoded calldata) and use cases (forensic analysis, MEV inspection, contract-call breakdown). This distinguishes it from sibling tools like get_address or get_block.

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?

Description provides explicit usage scenarios and required parameters ('Pass chain + tx_hash'). It indicates when to use the tool but does not explicitly mention when not to use it or name alternative tools, though the context implies distinct use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds detail about output content (chain slugs and host URLs), which is useful beyond annotations.

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

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

Two sentences, front-loaded with key action and result, no unnecessary words. Every part 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?

Given no parameters and presence of an output schema, the description fully covers what the tool does and its purpose. Sibling context doesn't require more detail.

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

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

No parameters exist; schema coverage is 100% with empty properties. Baseline for 0 params is 4; description doesn't need to add parameter info.

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

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

The description explicitly states the tool lists all EVM chain slugs and Blockscout host URLs, with specific examples. It clearly distinguishes from sibling tools by its focus on chain discovery.

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

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

The description directly tells the agent to use this tool to discover valid chain values for other tools, providing explicit 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by specifying return fields (id, type, params, created_at, last_fired_at, fire_count) and that it lists active subscriptions by default. No contradictions.

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

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

Two sentences with no redundant words. First sentence defines action and output, second gives usage guidance. Fits within minimal space.

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

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

No output schema, but description lists all return fields. Parameter is fully covered by schema. For a simple read operation, this is complete and 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 description coverage is 100%, so baseline is 3. Description mentions 'active subscriptions' which relates to the parameter 'include_inactive' but does not add significant meaning beyond the schema's parameter description.

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

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

Description explicitly says 'List the caller's active subscriptions' and lists return fields. Clearly distinguishes from sibling tools 'subscribe' and 'unsubscribe' by stating usage: 'review what you're monitoring before adding more or to find an id to cancel'. Verb+resource is specific.

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: 'review what you're monitoring before adding more or to find an id to cancel'. Implicitly says not to use for subscribing/unsubscribing. Slightly lacks explicit exclusion but context is clear.

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

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

Though annotations indicate this is not read-only/idempotent/destructive, the description adds substantial behavioral context: rate limit ('5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token flow for anonymous reports, how to later retrieve resolution status, and the human impact ('team reads digests daily and signal directly affects roadmap'). No annotation contradiction exists.

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

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

The description is longer than average but tightly packed: each sentence adds a distinct, non-redundant fact (scope, triggers, exclusions, token flow, rate limits, roadmap). It is front-loaded with purpose and then proceeds logically through usage, constraints, and feedback mechanics. No filler or repetition.

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 feedback tool with four parameters, nested context object, anonymous claim flow, rate limits, and cross-server boundary conditions, the description covers every relevant aspect. It explains what happens on submission (returns claim_token), edge cases (without account), follow-up (claim_token retrieval), and practical constraints (5/day, free). No output schema exists, but the description compensates fully.

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, so baseline is 3. The description goes beyond by explaining the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), reiterating that claim_token requires no other arguments, and adding message best practices ('Be specific... 1-2 sentences typical'). This elevates it slightly above schema-only.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete trigger conditions (bug, feature/data_gap, praise) and explicitly delineates scope ('ONLY for tools served by this Pipeworx connection'), clearly distinguishing it from sibling tools like ask_pipeworx 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 provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data...') and exclusions ('if the tool came from a different MCP server... file it with that server instead'). It even names the alternative action (file with that server) and clarifies how to identify Pipeworx tools, leaving no ambiguity.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description goes beyond by explaining the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and the window effect. 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 concise with no filler. It uses bullet points for use cases and separates technical details at the end. Every sentence provides distinct value.

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

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

Given 1 optional parameter and no output schema, the description fully covers the tool's purpose, output, and usage context. It is complete for an AI agent to decide when and how to use it.

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

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

Schema coverage is 100% and the parameter description already details the enum. The description adds value by explaining default window '24h' and the trade-off between short and long windows, which aids selection.

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 'Returns the top tools, top packs, and total call volume over a recent window', specifying a concrete verb and resource. It distinguishes from siblings by listing three specific use cases that no other 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 provides three explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It lacks explicit when-not-to-use or alternative tools but the context is strong enough for an AI agent to decide.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses algorithmic details: monotonicity violations, partition-sum checks, semantic anchor with Jaccard similarity, partition filter for placeholders, and fill check against live CLOB depth. It warns when realizable_edge_pp ≤ 0 implies no trade opportunity.

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

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

The description is well-structured with clear sections for each mode and response details. It is dense but efficient, earning its length. Minor note: it could be slightly more streamlined, but overall excellent.

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

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

Given the complexity of the tool (three modes, multiple checks, response structure), the description is fully complete. It covers purpose, parameters, behavior, response fields, and even edge cases like fill check and placeholder filtering, 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?

The description greatly enriches the schema: for 'event', it explains the slug format and the checks performed; for 'topic', it describes cross-event scanning and similarity filtering. The schema descriptions are minimal, but the tool description adds comprehensive context.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) with clear explanations, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises against trading when the fill check shows no realizable edge and references polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint) by detailing caching (1h KV-level), response structure (by_segment with diagnostics), and the internal logic of model families. It also explains edge cases like empty segments and reliability of fed signals. 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 and detailed but well-structured with logical sections (model families, knobs, response structure). It front-loads the purpose and then dives into specifics. While it could be more concise, the detail is justified given the tool's complexity and the need for agents to understand nuances. No wasted sentences.

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

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

Given the tool's complexity (9 parameters, no output schema), the description thoroughly covers all necessary aspects: three model families, tradeable-edge knobs, response segments, caching, diagnostics for empty segments, and special cases like fed markets. It provides a complete mental model for an agent to decide when to call 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%, so baseline is 3. The description adds value by explaining how parameters like min_kelly and min_partition_leg_kelly interact across different segments, and provides context for knobs like slippage_pp and liquidity. However, most parameter explanations are already adequate in the schema, so the addition is moderate.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It explicitly frames the use case as 'what should I bet on today' and distinguishes itself by scanning top markets without paging through hundreds. This specific verb-resource combination effectively differentiates it 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?

The description provides rich context on when to use this tool (for discovering betting opportunities) and explains tradeable-edge knobs and caching behavior. However, it lacks explicit comparison to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which would help agents choose between them. Despite this, the usage guidance is clear and practical.

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 significant behavioral detail: explains that edge_pp_net is signed (negative = SELL YES), trend categories, and decay calculation from daily closes. It also notes snapshot gaps and TTL limits.

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

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

The description is well-structured with clear sections: purpose, response fields, limits. Every sentence adds value. It's somewhat lengthy but efficient for the information density. Minor improvement could be grouping limits more concisely.

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 is provided, so the description must compensate. It thoroughly explains the response structure: tracked[], expired[], snapshot_dates[], including field meanings and caveats (e.g., decay from daily closes, lifespan median). It also covers limits like snapshot TTL and start date. This makes the tool fully understandable.

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%, but the description adds valuable context: default values (14 days, '1wk'), clamp ranges (2-30), and admissible window values (24hr | 1wk | 1mo). This goes beyond the schema descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself by focusing on temporal behavior rather than just listing edges.

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

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

The description explains when to use the tool: to differentiate fresh wide edges from old wide edges. It provides context about snapshot gaps and history limits. However, it does not explicitly mention when not to use it or compare with siblings like polymarket_edges, but the context is clear enough.

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

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), identifies thin legs and forced directional risk, and explains partial fill dangers. 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?

Front-loaded with core purpose, then separates single-market and basket details. Though lengthy, every sentence contributes necessary information due to high tool complexity. Minor improvement possible by grouping parameter explanations more tightly.

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 all return fields (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, forced_directional_risk, etc.), making the tool's behavior fully predictable. Covers both modes comprehensively.

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

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

Schema coverage is 100% (all 4 parameters described). The description adds context beyond schema: explains default values, size interpretation across modes, and side auto-detection logic for baskets. This provides meaningful additional 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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifying two modes (single-market and basket) with distinct behaviors. This differentiates it from related tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage signals or trades above $500, and warns of risks like partial basket fills converting arb to directional positions. This provides clear when-to-use and when-to-avoid guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it details compatibility_warning conditions, temporal alignment checks, skipped cross types, and explicitly states that most pre-mapped topics are not tradeable. No contradictions with annotations.

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

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

The description is dense and contains a lot of useful detail, but it is somewhat verbose and includes run-on sentences. It is structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with purpose. It could be more concise while retaining the necessary information.

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

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

Given there is no output schema, the description thoroughly explains the return values (leg-by-leg prices, matched spread top_spreads_pp) and safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers input modes failure conditions, and data quality nuances, 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 description coverage is 100% and the description adds additional context beyond the schema. It explains the two modes, lists the 10 topic shortcuts, clarifies that explicit parameters override topic, and provides examples. This adds value but the schema already does a good job.

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 calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains what the response includes. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, so it loses one point.

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 guidance on when to use: for comparing same-outcome pricing across venues. It explains two modes and warns that most pre-mapped topics return compatibility_warning, indicating when the tool may not yield tradeable spreads. It gives explicit conditions under which spreads are invalid (compatibility_warning, temporal misalignment). No explicit alternatives are mentioned, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, etc.), description adds scoping detail (anonymous IP, BYO key hash, account ID) and behavior when key is omitted. 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?

Two sentences with clear structure, front-loaded with primary action, and efficient use of words. No unnecessary content.

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

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

Description sufficiently covers retrieval and listing, scoping, and pairing with siblings. Lacks explicit return format, but for a simple tool with no output schema, it provides adequate context.

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

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

Schema covers parameter fully (100% coverage) with description and example. The tool description reinforces behavior but adds no new semantic detail beyond what the schema already provides.

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

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

Description clearly states the tool retrieves saved values or lists keys, with specific verb-resource pairing and distinct use cases. Sibling tools like remember and forget are explicitly mentioned, differentiating recall's role.

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

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

Describes when to use (look up stored context) and pairs with remember/forget, providing clear context. However, it does not explicitly state when not to use or compare with other lookup tools.

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

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

The description discloses the mark_read parameter that modifies state (marking events as read), which contradicts the readOnlyHint annotation. Despite providing useful behavioral info, the contradiction warrants a score of 1 per rules.

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

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

The description is well-structured and front-loaded, with each sentence adding value. It could be slightly shorter but remains efficient.

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

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

Despite no output schema, the description details return fields and mentions alternative access method. All 5 parameters are explained, and the tool's context is complete.

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

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

With 100% schema coverage, the description adds clear meaning for each parameter: explains type filtering, limit range, since format, mark_read effect, and unread_only behavior, going beyond the schema descriptions.

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

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

The description clearly states it pulls recent alerts from the subscription feed, specifies key fields returned (source, citation_uri, raw payload), and provides filtering options. It distinguishes itself from sibling tools like ask_pipeworx or search by focusing on subscription feed events.

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 explains that polling works fine and provides an alternative URL for scripts/dashboards, implying when to use the tool versus direct access. However, it does not explicitly state when not to use it or compare to other sibling tools.

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

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

Discloses fan-out to multiple sources with fallback logic (GDELT preferred, GNews when rate-limited/5xx), notes USPTO soft-fail due to API sunset, and describes return structure (changes grouped by source, total_changes count, citation URIs). Annotations already indicate read-only, non-destructive, idempotent; description adds significant behavioral context without contradiction.

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

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

Description is information-dense but well-structured: starts with example queries, explains function, parameters, return structure, and alternative tool. Slightly verbose but all sentences earn their place. Could be more concise, but clear and front-loaded.

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

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

Given complexity (multiple sources, fallback, date formats, alternative sibling), description is remarkably complete. Covers purpose, parameters, behavior, return values (changes[], total_changes, citation URIs), and when to use alternative. No output schema exists, but description adequately explains output.

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 beyond schema by explaining since formats (ISO date or relative shorthand with examples like '7d', '30d'), value accepts ticker or CIK, and type only supports 'company'. Enhances understanding for correct invocation.

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

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

Description clearly states tool provides a change feed for a company over a time window, aggregating from SEC EDGAR, GDELT/GNews, and USPTO. It gives example queries and distinguishes from entity_profile, which is a sibling tool for static profiles.

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

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

Explicitly recommends when to use this tool (change feed) vs entity_profile (static profile). Provides examples of valid since values (ISO dates or relative shorthand) and suggests '30d' or '1m' for typical monitoring.

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 idempotentHint true, destructiveHint false, readOnlyHint false. The description adds valuable context beyond annotations: persistence behavior for authenticated vs anonymous sessions, and scoping by identifier. 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: first states purpose, second provides usage guidance, third gives technical details. No wasted words, front-loaded effectively.

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

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

Given the simplicity of the tool (store key-value) and the presence of full schema descriptions, the description covers all necessary context: purpose, usage, persistence, and relation to siblings.

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

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

Schema coverage is 100% with clear descriptions. The description enhances by providing naming conventions and examples (e.g., 'subject_property'). This adds meaning beyond the schema.

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

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

The description clearly states the verb 'Save' and the resource 'data the agent will need to reuse later'. It distinguishes itself from sibling tools like recall and forget by mentioning them explicitly.

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

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

The description provides explicit guidance on when to use this tool ('when you discover something worth carrying forward') and mentions pairing with recall and forget, offering 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?

The description adds substantial behavioral context beyond the annotations: it discloses that each call cascades through several lookup endpoints, that LEI/FIGI enrichment degrades gracefully when external services are unavailable, that identifiers are labelled with their source, and that unresolved identifiers are explicitly stated under 'unresolved' rather than omitted. This enriches the agent's understanding of internal behavior and failure modes, which annotations alone do not provide.

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

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

The description is long but information-dense, with a clear structure: example queries first, then the primary purpose, followed by supported types and details. Every sentence provides useful information, though the list of example queries could be shortened without losing essential meaning. It is slightly verbose but well-organized, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, internal cascading calls), the description is remarkably complete. There is no output schema, but the description explains the output format (identifier labels with source, explicit 'unresolved' field) and covers degradation behavior. It also mentions how this tool replaces 2-3 manual lookups, giving a sense of effort and scope. The description provides sufficient context for an agent to decide when and how to use the tool.

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

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

Although the schema covers both parameters with 100% coverage, the description goes far beyond the schema by explaining the semantic meaning of each 'type' and 'value' pair. For company, it details what identifiers are returned (CIK, ticker, company_name, LEI, FIGI) and the accepted input formats (ticker, CIK, or name). For drug, it specifies RxCUI, ingredient, brand, and example values. This additional context meaningfully aids correct parameter usage.

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

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

The description clearly states the tool's function with a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), provides multiple example queries, and explicitly distinguishes it from siblings by saying 'Use FIRST whenever you have a name but need an ID.' It also explains the use case as a precursor to other tools that require identifiers, leaving no ambiguity about what it does.

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

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

The description offers explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and the specific inputs each accepts, including examples of ticker, CIK, and drug names. The note about graceful degradation of LEI/FIGI enrichment gives context on when to expect incomplete results, helping the agent decide if this tool is appropriate.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds behavioral details: it probes each entity using 'ai_visibility_check', ranks results by score, and surfaces most/least recognized. This adds value without contradicting annotations.

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

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

Two sentences with zero wasted words. The main action is front-loaded, followed by a brief explanation of process and a concrete use-case example. 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?

There is no output schema, but the description explicitly states returns: 'ranked list with score, confidence, signal density per entity'. It covers parameter roles and the tool's purpose sufficiently for a multi-entity comparison tool with clear annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by stating that the first entity in 'entities' is treated as the 'subject' and the rest as competitors, which is not captured in the schema. This provides actionable guidance beyond the schema's descriptions.

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

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

The description clearly states the tool's action ('Compare AI visibility across multiple entities side-by-side') and specific resource ('AI presence'). It also distinguishes itself from sibling tools like 'ai_visibility_check' and 'compare_entities' by emphasizing multi-entity comparative 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?

The description explicitly situates the tool's usage in competitive AI-marketing audits and provides a concrete use-case question. It implies when not to use (if only a single entity is needed) and mentions that the first entity is treated as the 'subject' for narrative, guiding the agent on parameter ordering.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable context about partial failures, bundlephobia latency (5-30s), graceful degradation, and sources_failed.

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

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

The description is relatively long but well-structured and front-loaded with key information. Every sentence adds value, though a very slight reduction in length could improve conciseness.

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

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

No output schema, but the description thoroughly explains the return structure (summary block, per-advisory details, links, alternative versions). Also covers NPM-only scope and graceful degradation, making the tool self-contained.

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

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

Schema has 100% coverage for both parameters. Description adds context about scoped packages and version defaulting to latest, which improves over schema alone but is not extensive.

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 as a composite check for npm packages, combining deps.dev and bundlephobia. It distinguishes from siblings by specifying 'NPM ecosystem only in v1' and mentions alternatives like deps.dev:version.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies NPM-only and notes fallback for other ecosystems.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, non-destructive query. The description adds value by specifying the scope (addresses, transactions, blocks, tokens, ENS names) and that it operates on a specific EVM chain, but it does not disclose any additional behavioral traits like rate limits, pagination, or error handling.

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 two sentences that front-load the core action and then provide usage context. Every sentence adds value without redundancy. It is appropriately sized for a simple tool.

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

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

Given the tool's low complexity (2 string params) and the presence of an output schema (which presumably defines response structure), the description is mostly complete. It explains the tool's purpose and when to use it. However, it could benefit from mentioning whether the search returns multiple results or how to interpret ambiguous queries.

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 0% with no descriptions for the two parameters. The description provides only a template ('Search [chain] for [query]') and examples, without specifying allowed chain values or the format of query. It fails to compensate for the lack of schema descriptions, leaving the agent to guess or rely on external knowledge.

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 performs universal block-explorer search across addresses, transactions, blocks, tokens, and ENS-style names on an EVM chain. The template 'Search [chain] for [query]' and examples clarify the action. However, it does not explicitly differentiate from sibling tools like 'search_within' or 'get_address', relying on the agent to infer the difference.

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

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

The description provides explicit guidance: 'Use when you don't know yet whether the input is an address / hash / token symbol.' This tells the agent when to invoke this tool instead of specific getters. It does not mention situations where it should not be used, but the context is clear enough for the intended use case.

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

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

Goes beyond annotations by detailing embedding model, window size, truncation at 200K chars with flagging, and output format (character offsets, similarity scores). 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?

Concise, front-loaded core statement, each sentence adds value. No wasted text; covers purpose, usage, and technical details efficiently.

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?

Fully explains input/output behavior despite no output schema; includes truncation handling and integration with sibling tool. Complete for agent understanding.

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

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

Schema covers all parameters with descriptions; description adds value with example queries and context for the 'text' max size. Slightly exceeds 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?

Clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K) and differentiates from sibling by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly explains when to use (record too large for prompt) and references an alternative (ask_pipeworx_grounded). Provides clear context for appropriate usage.

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

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

Adds value beyond annotations: account requirement, delivery channel limits (SMS cap), webhook HMAC signing, auto-disable after failures. No contradiction with annotations (readOnlyHint=false, destructiveHint=false). IdempotentHint=true is ambiguous but not contradictory.

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

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

Description is long but well-structured: purpose, prerequisites, types with examples, delivery channels. Every sentence adds value; no redundant information. Slightly verbose but appropriate for complexity.

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

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

Comprehensive for a creation tool: covers types, delivery, prerequisites, and references sibling tools. Lacks error scenarios or return value details beyond 'subscription id', but 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% (baseline 3). Description adds rich examples for each type and detailed explanation of delivery channels, including constraints and verification steps, significantly enhancing schema info.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Verb (create) and resource (subscription) are explicit, and it distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Prerequisites (Pipeworx OAuth account) are stated. Supported types and delivery channels are detailed. Implicitly contrasts with sibling tools like recent_alerts for reading alerts, but no explicit when-not-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 the tool as read-only, idempotent, and non-destructive. The description adds context about returning dynamic content from a live catalog and the ability to filter by topic, which goes beyond annotations.

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

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

The description is clear and well-structured, starting with example phrasings and ending with usage guidance. It is slightly verbose but every part 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 lacking an output schema, the description fully explains what the tool returns: category-bucketed example questions with tool shapes. It covers all necessary context for effective use.

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

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

Schema coverage is 100%. The description adds meaning by explaining the optional topic parameter with enumerated values and advising to omit for a cross-category spread, which aids correct invocation.

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

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

The description clearly states the tool's purpose: to return category-bucketed example questions with exact tool and argument shapes, serving as an onboarding entry point. It distinguishes itself from sibling tools by being the first tool to use when exploring 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 tells the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear context and timing for 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?

Adds critical behavioral details beyond annotations: row is deactivated (soft delete), historical events preserved, ownership enforced. Annotations already indicate non-destructive, idempotent, not read-only; description enhances with soft-delete nuance.

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

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

Two concise, front-loaded sentences. No redundancy or filler. Every phrase adds distinct information.

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

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

Single required parameter, no output schema, annotations present. Description fully covers behavior, ownership, and persistence, leaving no 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?

Schema covers 100% of parameters; description only restates parameter purpose without adding new semantic details. Meets baseline but adds no extra 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?

Clear verb ('Cancel') and specific resource ('subscription by id'). Implicitly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by stating cancellation action.

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

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

Notes ownership enforcement ('only your own subscriptions') and effect (deactivation vs deletion). Does not explicitly mention when to use over alternatives, but context is sufficient.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds significant behavioral context beyond that: the meaning of each verdict (confirmed, refuted, etc.), the critical distinction between 'could_not_verify' and 'unsupported', and the fact that it returns verbatim evidence with pipeworx:// citations. This is exactly the kind of disclosure that helps an agent trust and interpret results.

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

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

Although lengthy, every sentence serves a purpose: examples for recognition, routing rules, verdict list, caller warnings, and a note about replacing 4–6 sequential calls. The content is front-loaded and well-structured, flowing from what it does to how it behaves to what callers must know.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error handling) and the absence of an output schema, the description covers all essential aspects: return values, citation format, reasoning, and the semantic distinction between could_not_verify and unsupported. It is complete enough for an agent to use the tool correctly and interpret its output appropriately.

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 descriptive parameter docs, so baseline is 3. The description goes further by explaining how tolerance_pct interacts with claim wording and suggesting values (1–2) for hallucination detection, and by giving concrete example claims. This adds meaning beyond the schema without being redundant.

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

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

The description opens with concrete example phrasings and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It explicitly distinguishes two routing paths (SEC EDGAR/XBRL fast path for company-financial claims vs. grounded pipeline for all others), which differentiates it from sibling tools like search or ask_pipeworx_grounded.

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

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

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the routing logic for claim types. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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