Mempool Space

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

Annotations already cover read-only, open-world, idempotent, non-destructive. Description adds value by detailing the probe behavior, per-model return structure, and that Anthropic calls are billed to user.

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

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

Concise, front-loaded with core action, every sentence adds value. No fluff.

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

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

No output schema, but description explains return format (per-model objects + combined view). Covers all key aspects for agent usage given tool 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?

All 4 parameters have schema descriptions. Description adds examples for entity, explains default model, and clarifies _apiKey usage, going beyond schema.

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

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

Description clearly states the tool probes LLMs and scores visibility, with specific verb and resource. Sibling tools are mostly unrelated (Pipeworx, Bitcoin, Polymarket), so it differentiates well.

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

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

Explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Default model and BYO key explanation provide clear context, though no explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds context about routing behavior, citation URIs, and tier availability. While it doesn't mention rate limits or auth, the annotations cover the safety profile, and the description enriches understanding of what the tool does under the hood.

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 every sentence earning its place. It front-loads the most important instruction ('PREFER OVER WEB SEARCH'), then clearly explains the routing behavior, gives examples, and specifies alternatives—all without fluff.

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

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

For a tool with no output schema, the description adequately sets expectations by mentioning 'structured answer with stable pipeworx:// citation URIs.' It covers when to use the tool, how to escalate, and what kinds of questions it handles, making it complete for the given 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?

The input schema has 100% coverage, with all parameters (question and aliases) described. The description adds usage examples but no parameter-specific semantic details beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

The description explicitly says 'START HERE for most questions' and positions it as the default entry point. It provides concrete when-to-use vs. when-not-to-use guidance by specifying that ask_pipeworx_grounded is for hallucination-resistant single answers, deep_research is for broad/multi-part questions, and breaking news is already handled.

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 reveals that no candidate is currently active and that it 'currently matches ask_pipeworx exactly', providing concrete behavioral context beyond the annotations. It also discloses that it 'Falls back to nothing' and is a full working router, confirming it doesn't have hidden limitations. This aligns with readOnlyHint and idempotentHint without contradicting them.

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

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

The description is three sentences, front-loaded with the key identity ('Beta version of ask_pipeworx') and core functionality ('identical universal router'). The later details about the last retired date and comparison process are useful and earn their place without being verbose.

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

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

Given the tool is a router with no output schema, the description adequately covers what it does, its current state, usage, and relationship to the stable version. It mentions 'same response shape' to address return values despite no output schema, making it complete for an agent to use correctly.

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

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

The input schema already has 100% coverage by defining all six parameters as aliases for 'question', so the description adds no additional parameter meaning. Per the rubric, baseline 3 is appropriate when schema covers the parameters; the description does not need to restate them.

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

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

The description clearly states this is the 'Beta version of ask_pipeworx' and characterizes it as an 'identical universal router (same 5,529 tools, same arguments, same response shape)'. This gives a specific verb+resource+scope, and the experimental status distinguishes it from the sibling 'ask_pipeworx'.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', which is a clear when-to-use directive. It also contrasts with the stable router by noting results are compared to decide what merges, implying the alternative is the stable ask_pipeworx.

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 rich behavioral details beyond annotations: refusal reasons, success/refusal return shapes, and the fact that answers are extracted only from tool results. Even with annotations declaring readOnlyHint, the description adds context about refusal behavior and 'fetched_at' fields, which is valuable for the agent.

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

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

Every sentence earns its place: defines the mode, explains routing, specifies grounding, lists refusal reasons, gives usage guidance, and notes cost tradeoff. Front-loaded with the core purpose, 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 absence of an output schema, the description fully specifies the return format for both success and failure cases. It also explains the operational behavior (routing, extraction, refusal reasons) and cost implications, making the tool self-contained and clear.

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

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

Schema coverage is 100% for all 6 parameters (all aliases for a single question string). The description does not add parameter-specific syntax or examples, but since the schema already fully documents them, a baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that extracts answers using only tool results. It explicitly distinguishes itself from ask_pipeworx by emphasizing grounding and return structure, 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 states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost tradeoff (extra LLM call), providing clear decision criteria.

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

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

The description extensively discloses behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract (match confidence, alternatives), parent_event extractor, news fallback fields, safety mechanisms (low_confidence, market_closed), wide-spread warnings, and resolution-rule risk. No contradiction with annotations (readOnlyHint is fine as it's querying data).

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

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

The description is front-loaded with the main purpose and is very informative, but it is lengthy with many examples and edge cases. While thorough, it could be more concise for agent consumption. Every sentence is justified, but the sheer length impacts conciseness slightly.

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

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

Given the tool's complexity, the description is highly complete. It covers input, behavior, response shapes, safety, and edge cases without an output schema. It provides enough detail for an agent to understand functionality, guarantees, and limitations.

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 value by explaining input formats for 'market' (slug, URL, question text), enum values for 'depth' (quick/thorough with default), and usage guidance for 'include_raw' (when to set true for full payloads). This goes 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from siblings like polymarket_arbitrage and polymarket_edges through its focus on general bet research.

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

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

The description explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It provides clear context but does not explicitly state when not to use or name alternative tools. Sibling tools imply alternatives, but explicit exclusions are missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully cover safety and idempotence. The description adds context about returning the 'current chain tip' but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

A single sentence that is front-loaded with the verb and resource, containing no extraneous words. Every word earns its place.

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

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

For a simple tool with one optional parameter and an output schema, the description covers all necessary context: the action, the resource, and the supported networks. 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 coverage is 100%, and the parameter description in the schema is already comprehensive (including accepted aliases). The tool description merely restates the network options, adding no new semantic 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 specifies the verb 'Return', the resource 'chain tip block height', and the scope 'for mainnet, testnet, signet, or liquid'. This clearly distinguishes it from sibling tools like get_block which return full block 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 clearly states when to use the tool (to get the latest block height on supported networks). Given the simplicity of the tool and the fact that no sibling provides exactly this, explicit exclusions are not necessary. Still, no guidance on when not to use it 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 (readOnlyHint, openWorldHint, etc.) are complemented by description that covers fiscal year handling, sorting by primary metric, and return format with URIs. No contradictions; adds useful behavior beyond annotations.

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

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

Description is comprehensive but front-loaded with trigger phrases. Every sentence adds value, though the fiscal year handling detail could be a separate note. Minimal waste.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description covers inputs, behavior, sorting, and return structure. It replaces 8-15 sequential lookups, making it complete for an AI agent.

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

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

Schema has 100% coverage; description adds meaning by explaining what data each type pulls (SEC 10-K data for companies, FAERS for drugs) and providing examples ('AAPL, MSFT'), significantly enhancing the schema.

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

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

The description clearly states the tool compares 2-5 companies or drugs in one call, providing side-by-side data. It lists trigger phrases and explains the difference between entity types, distinguishing it from sequential sibling tools.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. Does not list when not to use but provides sufficient 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false; the description adds extensive behavioral detail beyond that: account/paywall requirements, parallel facet decomposition, findings packet with gaps[] (never invented), contradictions[], hop field, citation_uri fetchability, semantic excerpting, and latency expectations. 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?

Though long, every sentence adds a distinct operational detail: account requirement, source catalog, tool routing, output packet structure, gaps behavior, depth semantics, citations, and timing. It is front-loaded with the most critical constraint (account requirement) and contains no filler or redundancy.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It covers prerequisites, selection criteria, internal processing, return format components (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), and performance expectations, enabling an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, and the description further enriches meaning: depth values are elaborated ('quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop... contradictions[] scan)', 'thorough=8 (paid; adds a full iterative hop...)'). The question parameter is stated as natural language, and broad/multi-part is explicitly supported.

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 a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'Decomposes your question into focused facets... routes each to the right one of 5,529 tools IN PARALLEL'. It explicitly distinguishes from siblings with 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx'.

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

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

Usage is explicitly guided: 'Best for broad/multi-part questions over structured data', and alternatives are given: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and when to fall back to ask_pipeworx.

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 results are 'ready to call directly, no second schema lookup needed,' which provides extra context about output usability 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 front-loaded with purpose, followed by domains, return details, and usage advice. Every sentence adds value with no wasted words given 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?

No output schema exists, but the description compensates by detailing what is returned (names, descriptions, schemas with examples). It covers usage context and constraints (default/max limit). Minor gap: error handling or prerequisites not mentioned.

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, and the description enriches understanding by explaining that the query is a 'natural language description' and listing example domains. Aliases are clarified, and the limit parameter is contextualized with defaults.

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 'Find tools' and specifies the resource (tools) with explicit domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by emphasizing it's the discovery tool to call first when browsing many options.

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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides example use cases and implies when not to use it (when you already know the tool).

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint). It details the data sources crawled (SEC EDGAR, XBRL, USPTO, news, GLEIF), the exact return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), and even notes a potential failure mode ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). No contradiction with annotations.

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

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

The description is front-loaded with example queries and a clear summary, then details the return structure. While slightly lengthy (several lines), every sentence adds necessary information. A minor improvement could be grouping the return fields more compactly, but it remains efficient.

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

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

Despite the lack of an output schema, the description comprehensively explains all return values and their sources. It covers failure cases (patents soft-fail), prerequisites (use resolve_entity for names), and the 'one parallel call' nature. This fully compensates for the missing output schema given the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that 'names not supported' and specifying that CIK must be zero-padded, and by providing examples ('AAPL', '0000320193'). This helps the agent use the parameters correctly.

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

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

The description explicitly states the tool's purpose as providing a 'full cross-source profile of a US public company in ONE parallel call.' It includes concrete example queries ('Tell me about X', 'research Acme') and distinguishes itself from siblings like 'resolve_entity' and 'compare_entities' by stating it should be preferred over chaining single-source lookups for holistic views.

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

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

The description provides clear when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explicitly states when not to use it ('names not supported') and directs to the alternative sibling 'resolve_entity' if only a name is available.

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 destructive and idempotent nature. The description adds context about clearing sensitive data and pairing with siblings, 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?

Three concise sentences, each serving a distinct purpose: purpose, usage, and sibling pairing. No fluff.

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

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

For a simple delete-by-key tool with one required parameter and sufficient annotations, the description covers all necessary aspects: action, when to use, and relationship to other tools.

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

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

Only one parameter 'key' with full schema description coverage (100%). Description adds no further detail beyond what the schema provides.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource, distinguishing it from siblings like 'remember' and 'recall'.

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 scenarios for use ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with siblings, but lacks 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 indicate read-only, idempotent, non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown, providing context beyond the 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 a single, efficient paragraph with three sentences: purpose, mechanism, use cases. No extraneous information, 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?

The description covers purpose, mechanism, output format, and use cases. It lacks mention of error handling or limitations, but for a simple tool with 2 parameters and no output schema, it is sufficiently complete for an agent to use correctly.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds no new parameter details beyond the schema, but contextualizes them in the workflow. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file for any URL', and the purpose 'so AI crawlers can index the site cleanly'. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor indexing. While it doesn't state when not to use, the use cases are specific enough to guide appropriate invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering most behavioral aspects. The description adds minimal extra by specifying the output contains UTXO and tx counts, which is useful but not substantial 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 extremely concise (3 words) and front-loaded. It avoids unnecessary verbiage but could be slightly more informative without losing conciseness, e.g., mentioning it is a summary.

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

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

For a simple tool with 2 parameters and an output schema, the description is minimally adequate. It does not explain return structure (though output schema exists) or when to prefer this over related tools. It could be more complete given the sibling 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 coverage is 50%, with the 'address' parameter lacking description in the schema and the description not compensating. The 'network' parameter is well-documented in the schema (enum, defaults, aliases), so no additional value from description. Overall, the description adds no parameter meaning beyond what is already in the schema.

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

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

Description explicitly states it returns an address summary with UTXO and transaction counts. This clearly distinguishes it from sibling tools like get_address_transactions, which likely returns full transaction data. Verb and resource are implied and obvious.

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?

No guidance on when to use this tool versus alternatives like get_address_transactions or get_tx_status. The description does not mention usage context, prerequisites, or exclusions, leaving the agent to infer from sibling names.

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 non-destructive, so the safety profile is covered. The description adds valuable context: data source (mempool.space API), default network (mainnet), result limit (up to 50), and returned fields. It does not mention rate limits or API quirks, but this is a read-only operation with clear behavior. 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?

The description is two sentences, front-loaded with the core purpose, and every clause provides useful information: data source, network options, result limit, return fields, and use case. 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?

With an output schema present and annotations covering safety, the description provides a complete picture: what it does, data source, network selection, limits, return fields, and a typical use case. The tool is moderately simple, and the description adequately covers all dimensions.

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 67%: limit and network have descriptions, but address is undocumented in the schema. The description mentions network defaults and that the tool returns transactions for one address, but does not explain address format or semantics beyond an example. Since the schema covers most parameters and the description adds little beyond it, a baseline of 3 is appropriate.

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

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

The description clearly states a specific verb (get) and resource (address transactions), and scopes it to 'recent Bitcoin transactions touching one address', distinguishing it from sibling tools like get_transaction (single transaction) and get_address (address details).

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

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

The description implies when to use it: 'Answers what a BTC address has been sending or receiving lately.' It also mentions reading from mempool.space API and network options, but does not explicitly state when not to use it (e.g., for historical data or full transaction details). Sibling differentiation is implicit through scoping, but no explicit alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context such as authentication requirements, rate limits, or side effects, which is acceptable but provides no extra value beyond the annotations.

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

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

The description is extremely short (one phrase) and front-loaded with the key action and identifier. Every word earns its place; no redundancy. The brevity is effective 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 parameters, output schema exists, rich annotations), the description is remarkably complete. The schema and output schema fill in details about network defaults and return format. The description covers the core purpose sufficiently.

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

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

Schema coverage is 100%, so the input schema already documents both parameters with descriptions and an enum for network. The tool description does not add new meaning beyond stating 'hash or height,' which mirrors the parameter description. Baseline score of 3 is appropriate.

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

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

The description 'Block detail by hash or height.' clearly specifies the action (get detail) and resource (block), and unambiguously identifies the two identifier types (hash or height). It distinguishes from sibling tools like get_transaction or get_address which operate on different resources.

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 no explicit guidance on when to use this tool versus alternatives (e.g., using get_transaction for transactions or get_address for addresses). Usage is implied but not stated, and there are no 'when not to use' or exclusion criteria.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds actionable detail on return content (inputs, outputs, fee, etc.) and supported networks, exceeding what annotations offer.

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 sentence front-loads purpose and key elements. Every word earns its place; no fluff.

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

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

Given output schema exists, description needn't explain return values. Covers all essential input info and what the tool provides. Annotations confirm safe, idempotent behavior. Complete for a transaction fetcher.

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% (network param described). Description lists networks but adds no new semantics for txid or beyond schema. Minimal added value over structured data.

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

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

Description clearly states verb (Fetch), resource (transaction detail), and specific data fields (inputs, outputs, fee, size, confirmation status). Lists supported networks, distinguishing from siblings like get_tx_status.

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?

Specifies required input (txid) and optional network. Implicitly differentiates from get_tx_status by focusing on full detail, but lacks 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the specific return fields (confirmed, block hash, block height), which is useful but not extensive.

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

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

The description is a single, well-structured sentence that front-loads the key purpose and return details. No unnecessary words.

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

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

The tool has an output schema (not shown but present), so the description doesn't need to detail return values. However, it might benefit from mentioning error states or txid format, but given simplicity, it is reasonably complete.

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

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

Schema coverage is 50% (network has a description, txid does not). The tool description does not compensate by describing txid format or constraints. It only mentions 'txid' in the return context, not the input parameter specifics.

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 confirmation status (confirmed, block hash, block height) for a given txid, emphasizing that it avoids fetching the full transaction body. This distinguishes it from siblings like get_transaction, which would return the full body.

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 implicitly tells when to use this tool: when only confirmation status is needed and the full transaction body is unnecessary. It does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the context that it returns historical data (hashrate and difficulty), which is useful but does not contradict or add significant new behavioral traits beyond what annotations imply.

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

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

The description is extremely concise—one short sentence that is front-loaded and easy to parse. While it could include more context (e.g., return format), it wastes no words and is appropriately brief 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 optional parameters, output schema exists), the description is fairly complete. It clearly states the core data returned (hashrate + difficulty history). The output schema likely specifies return format, so the description covers essential context without needing elaboration.

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

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

Schema coverage is 100%, so the schema already documents both parameters (period and network) with descriptions and defaults. The tool description adds no additional semantic meaning for parameters beyond what is in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'Network hashrate + difficulty history', which is a specific verb-object pair. However, it does not distinguish from siblings like 'mining_pools' or 'block_height', which might also relate to mining or blockchain 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?

No guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, when-not-to-use, or related tools. The agent must infer usage context from the tool name and schema.

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, idempotentHint, destructiveHint. Description adds value by detailing return fields, 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 concise sentences, no extraneous information. Purpose, output fields, and usage guidance are efficiently communicated.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers essential elements: purpose, output, usage. Lacks mention of potential rate limits or pagination, but these are not critical for a simple list tool.

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

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

Schema coverage is 100% and description does not add meaning beyond schema; the single parameter include_inactive is sufficiently documented in schema.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates returned fields. Distinguishes from sibling tools subscribe and unsubscribe by focusing on listing.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use but clear context.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the description adds minimal behavioral context beyond stating the tool returns current statistics. No contradictions.

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

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

Description is a single, front-loaded sentence 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 simple nature of the tool and the presence of an output schema, the description sufficiently covers what the tool returns and its overall 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?

The input schema describes the single parameter with enum values and aliases. The description does not add meaning beyond what the schema provides, and schema coverage is 100%.

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 returns current mempool size, transaction count, and total fees. It is a specific verb+resource with a clear scope, and it is distinct from sibling tools like block_height 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?

No guidance on when to use this tool vs alternatives (e.g., recommended_fees). No when-not or preconditions mentioned.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds no extra behavioral context (e.g., data freshness, exclusion of unknown pools) to guide the agent.

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

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

The description is extremely short (3 words) but at the cost of clarity; it does not provide enough information to be useful despite being 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 the tool's simplicity and presence of an output schema, the description is still too sparse to convey the tool's purpose and scope adequately.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional meaning beyond what is in 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 'Block share by mining pool.' is vague; it does not clearly state that the tool returns the distribution of block contributions across pools, nor does it distinguish from related tools like hashrate.

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?

No usage context is provided; there is no indication of when to use this tool over alternatives (e.g., hashrate) or any prerequisites.

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

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

The description goes well beyond the annotations by disclosing rate limits ('5 per identifier per day'), the claim_token workflow for tracking resolution, the fact that it's free and doesn't count against quota, and the read path for checking updates. This adds meaningful behavioral context that annotations alone cannot convey.

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

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

The description is dense and well-organized, front-loading the core purpose and then covering usage, exclusions, and behavior. It could be slightly trimmed (e.g., the 'team reads digests daily' sentence is motivational but not strictly invocation-related), but every sentence delivers relevant information, making it appropriately sized for 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?

Given the absence of an output schema, the description fully explains the return behavior (claim_token) and its subsequent use for checking status. It also covers rate limits, scope, and what constitutes appropriate feedback, providing complete contextual grounding for an agent to decide when and how to invoke 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 documents all four parameters (100% coverage), the description adds practical usage detail: it instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and explains how to pass back a claim_token to read resolution status. This enriches the message and claim_token parameters beyond their schema definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource combos. It enumerates concrete feedback categories (bug, feature, data_gap, praise), and clearly distinguishes this tool from sibling query tools by framing it as a reporting mechanism.

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

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

The description explicitly states when to use the tool (bug, feature, data_gap, praise) and when not to (tools from a different MCP server), even offering an alternative: 'file it with that server instead.' It also provides a heuristic for identifying Pipeworx tools, making the decision boundary clear.

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

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

Annotations already declare readOnly and idempotent hints. The description adds value by detailing the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). 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 a single, well-structured paragraph that front-loads the key output, then lists use cases, and ends with behavioral notes. Every sentence adds value with no fluff.

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

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

Despite the tool's simplicity, the description covers purpose, usage context, parameter semantics, return structure, caching, and privacy. No output schema exists, so the description adequately explains what is returned.

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

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

Schema coverage is 100%, but the description adds meaning beyond the enum description by explaining the trade-off between shorter and longer windows ('what's hot right now' vs 'steady-state demand').

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 trending data: top tools, top packs, and total call volume over configurable windows. It distinguishes itself from siblings by focusing on real-time usage signal rather than static 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?

Three specific use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). While no explicit 'when-not-to-use' or alternatives, 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 indicate readOnly and idempotent; the description adds detailed behavioral context like Jaccard similarity filter, partition placeholder filter, and fill check against CLOB depth, enriching transparency 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 verbose but information-dense with logical flow. Every sentence adds value; slight reduction possible without losing clarity.

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

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

Comprehensive for a complex tool. Covers return values, fill check details, and redirects to polymarket_fill_risk for custom sizing. No output schema, but the description compensates.

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 substantial context: explains modes with examples, internal operations, and response fields, significantly enhancing 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by specifying its unique methodology and modes.

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

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

Provides explicit guidance on when to use each mode (no args, event, topic) and recommends event for specific markets. Mentions fill check and when not to trade, but lacks explicit exclusion of 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 read-only, open-world, idempotent, and non-destructive behavior. The description greatly expands on this by detailing model families (e.g., crypto_price, news_momentum), caching (1h at KV level), diagnostics, and the Fed data note, providing comprehensive behavioral context beyond annotations.

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

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

The description is extremely long and detailed, reading like a mini-specification. While well-structured with sections and lists, it may be too verbose for an agent to quickly parse. Some details (e.g., exact model formulas) could be summarized for brevity.

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 9 parameters, no output schema, and complex internal logic, the description covers return structure (by_segment, fed_candidates, diagnostics), filter knobs, and caching. It provides enough information for an agent to understand and safely invoke the tool, making it nearly 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%, and the description adds significant value for each parameter, such as explaining min_kelly filters small opportunities, slippage_pp includes Polymarket fee context, and min_partition_leg_kelly addresses partition arb nuances. This goes far beyond schema descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and resources ('Polymarket markets', 'Pipeworx data'), and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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 frames the tool for 'what should I bet on today' and mentions discovering opportunities without paging hundreds of markets. It details filter knobs but lacks explicit guidance on when not to use it versus sibling tools, though the context implies it's the primary edge detection tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which the description complements by explaining snapshot-based data, response structure (tracked, expired, snapshot_dates), and limits (60-day TTL, start time). No contradictions. Adds rich behavioral context beyond annotations.

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

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

The description is well-structured with headers (ARGS, RESPONSE, LIMITS), front-loads the core question, and every sentence adds value. Despite length, it is concise and informative.

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

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

The description thoroughly explains the output fields (tracked with trend, decay, etc.; expired with lifespan; snapshot_dates) and constraints. No output schema is present, but the description compensates fully. Annotations cover safety. The tool is complex, but the description leaves no critical 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 coverage is 100%, and the description adds defaults (days=14, window='1wk'), constraints (max 30, clamped 2-30), and context (snapshot family). This enhances understanding 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, answering 'how long has this edge existed and is it shrinking?'. It is distinct from sibling tools like polymarket_edges (likely real-time edges) and other Polymarket tools. The verb 'track' aligns with the name and outcome.

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 the use case: distinguishing between fresh wide edges and old wide edges. It implicitly contrasts with real-time edge data (available via polymarket_edges). However, it does not explicitly state when not to use or name alternatives, leaving some ambiguity.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with description. The description adds crucial behavior: it walks the CLOB ladder, computes slippage, and warns that partial basket fills convert arb into unhedged directional positions – the dominant loss mode. This exceeds annotation coverage.

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

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

The description is verbose but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value. A minor reduction in length could be possible, but the complexity of the tool justifies the detail.

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 for both modes, explains edge cases (thin_legs, forced_directional_risk), and provides usage thresholds. For a risk-check tool with 4 params and no nested objects, this is comprehensive.

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

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

Schema coverage is 100%, but the description enriches all parameters: explains mode selection (market vs event), default side logic in basket mode (auto based on partition sum), and different size_usd interpretations (spend vs target proceeds vs settlement notional). This provides significant added meaning.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, lists return fields (top_of_book, vwap_fill_price, etc.), and explicitly ties usage to prior signals from polymarket_arbitrage and polymarket_edges. This sets it apart from siblings.

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

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

The description explicitly tells when to use this tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'). It also warns against using after partial fills due to directional risk. While it doesn't list alternative tools, the context ('before acting on...') makes the usage scenario 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?

Description adds extensive behavioral context beyond annotations: details on response fields (top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), conditions for non-tradeable spreads, and how the tool detects incompatible bet shapes. 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?

Well-structured and front-loaded, but somewhat verbose with detailed explanation of response fields. Could be slightly trimmed without losing clarity, but overall concise given the complexity.

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

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

Comprehensive despite lack of output schema: fully describes response fields, safety indicators, and usage caveats. The description enables an agent to understand when and how to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining mode interaction and providing example values, though it largely echoes schema details. Slight redundancy prevents a 5.

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 computes cross-venue spreads between Kalshi and Polymarket, with two modes (topic shortcuts and explicit tickers). This distinguishes it from sibling tools like polymarket_arbitrage which focus on a single venue.

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

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

Provides explicit guidance on when to use the topic mode vs explicit mode, warns that most pre-mapped topics return compatibility warnings, and explains conditions when spreads are not meaningful (temporal misalignment, non-equivalent bet shapes).

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that it retrieves values and lists keys, but does not provide new behavioral insights beyond what annotations convey. 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 short (3 sentences), front-loaded with the primary action, and each sentence adds value. No unnecessary words 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 simple tool with one optional parameter, rich annotations, and no output schema, the description fully covers the modes (with/without key), scope, and relationship to siblings. Complete and 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 covers 100% with a description for 'key'. The description adds practical semantics: omitting key lists all keys. This provides usage context beyond the schema's basic 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 retrieves a saved value or lists all keys, using specific verbs 'Retrieve' and 'list'. It distinguishes itself from sibling tools like 'remember' and 'forget' by focusing on retrieval.

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

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

The description provides explicit context: 'look up context the agent stored earlier', explains omitting key for listing, and mentions scoping. It also pairs with remember/forget. Though no explicit 'when not to use' is given, the use case is clear.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that mark_read:true flags events read, affecting subsequent calls. This mutation side effect is critical for agent behavior and is not covered by annotations. Also explains the feed persistence and return fields.

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

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

The description is three sentences, front-loaded with purpose, then details return fields, filtering, side effects, and alternative access. No unnecessary words, every sentence earns its place.

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

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

Given the tool has no output schema, the description explains return fields adequately. All parameters are described in schema and supplemented by examples in the description. Annotations are rich, and the description covers usage, side effects, and alternative access, making it comprehensive for an agent.

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

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

All 5 parameters have schema descriptions (100% coverage). The description adds value by giving concrete examples (e.g., 'sec_8k' for type) and explaining the mark_read parameter's behavior and implications. This enhances understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, with specific verbs and resource identification. It distinguishes from sibling tools (none are alert-specific), making the purpose unambiguous.

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

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

The description provides context for usage by explaining filtering options (type, since) and the mark_read side effect. It also mentions an alternative access method (GET endpoint for scripts/dashboards). However, it does not explicitly compare with sibling tools or state when not to use.

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

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

Discloses behavior beyond annotations: fans out to multiple APIs in one parallel call, fallback from GDELT to GNews, soft-fail for USPTO. Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false; description adds operational details.

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

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

Description is front-loaded with examples and structured logically. It is relatively long but every part adds value (examples, source details, date format, sibling differentiation). Could be slightly tighter, but remains clear and informative.

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

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

Given the tool's complexity (multiple data sources, date handling, fallbacks), the description covers all necessary aspects: input parameters, output structure (changes[] grouped by source, total_changes, URIs), and limitations. No output schema but description compensates.

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. Description adds context: type only supports 'company', since accepts relative shorthands, value accepts ticker or CIK, and recommends '30d'/'1m'. This justifies a score above baseline.

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

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

The description uses example queries ('What's new with X', 'latest on Y') and clearly states it returns a change feed for a company, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from the sibling tool entity_profile, making purpose unambiguous.

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

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

Explicitly tells when to use (recent changes with time window) and when not to (use entity_profile for static profile). Also provides guidance on date formats ('ISO date or relative shorthand') and suggests typical window ('30d' or '1m').

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, openWorldHint, and non-destructive nature. The description adds no further behavioral context (e.g., caching, rate limits, or data freshness). Given thorough annotations, the description's contribution is minimal, earning a baseline score of 3.

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, concise sentence that front-loads the key information. No unnecessary words or filler, making it efficient for an AI agent to parse.

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?

While the tool has an output schema (handling return values) and a simple input, the description lacks additional context such as network availability, typical fee ranges, or usage patterns. It is minimally adequate but could be more informative about when these recommendations are updated or their reliability.

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

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

The input schema has 100% coverage with a detailed description for the 'network' parameter (including aliases and default). The tool-level description adds nothing beyond what is already in the schema, so the score is 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 'Current sat/vB fee recommendations' clearly states the tool returns recommended fees in satoshis per vbyte. It uses a specific verb ('recommend') and resource ('fees'), and the simplicity distinguishes it from sibling tools like mempool_stats which might offer broader mempool 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?

No guidance is provided on when to use this tool versus alternatives such as mempool_stats or other fee-related tools. There is no mention of context, prerequisites, or scenarios where this tool is preferred or should be avoided.

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 context beyond annotations: scoped by identifier, persistence duration (persistent for authenticated, 24h for anonymous). No contradiction with annotations (idempotentHint=true, readOnlyHint=false).

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

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

Four sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

For a simple 2-param tool with no output schema, the description covers usage, persistence, behavior, and sibling pairing. 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 coverage is 100%, but the description provides example key names (e.g., 'subject_property', 'target_ticker'), adding value beyond schema descriptions.

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

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

Clearly states the tool saves key-value data for reuse across conversations/sessions. Distinguishes from siblings (recall, forget) by mentioning pairing with them.

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

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

Explicitly says when to use: when discovering something worth carrying forward like tickers, addresses, preferences. Does not explicitly state when not to use, but the positive guidance is strong.

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

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

Annotations already mark read-only/idempotent. The description adds valuable behavioral details: identifiers that cannot be resolved are listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable, and each call cascades through multiple endpoints. This significantly enhances transparency beyond the annotations.

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

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

The description is dense but well-structured, front-loading user examples and a clear purpose. It is somewhat long due to detailed per-type output, but each sentence provides useful information; a more structurally formatted version might be slightly easier to scan.

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

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

With no output schema, the description compensates by specifying the content of the result for each supported type, including the `unresolved` field and the `pipeworx://rxnorm/concept/{rxcui}` citation. It also explains fallback behavior, making it fairly 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?

The input schema already describes both parameters. The description adds meaning by detailing what each type returns (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and gives examples like 'AAPL' and 'metformin.' This goes well 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 resolves user-spoken names to canonical identifiers, with examples like 'What's the ticker for...' and explicitly says 'Use FIRST whenever you have a name but need an ID.' It distinguishes from siblings by describing the resolved identifiers and supported types.

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 advises 'Use FIRST whenever you have a name but need an ID.' However, it does not name alternative tools or provide when-not-to-use conditions, so it offers clear context but lacks exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds specifics: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density per entity. 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 pack purpose, usage hint, behavioral detail, and output summary. Every sentence earns its place; no redundancy. Front-loaded with core action.

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

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

Despite lacking output schema, description clearly states return content: ranked list with score, confidence, signal density. Explains probing process and parameter semantics fully. Annotations cover safety. Complete for tool complexity.

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

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

Schema coverage is 100% but description adds crucial semantics: entities first entry treated as subject, models list supported values (workers-ai, anthropic), _apiKey usage details, context role for disambiguation. Goes beyond parameter names to clarify behavior.

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

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

Clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. Differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by explaining it probes with ai_visibility_check and ranks entities. Provides concrete use case.

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

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

Explicit context provided: 'Useful for competitive AI-marketing audits' and a relatable question. Implies when to use but lacks explicit when-not-to-use or alternative comparisons, though sibling ai_visibility_check is implied as the single-entity alternative.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds critical behavioral details: composite fan-out to two services, 5-30s delay for first bundlephobia measurement, default version behavior, and the sources_failed field on partial failures. 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 a single paragraph, but it is well-structured with key information front-loaded. Every sentence provides useful detail, though a slightly more structured format (e.g., bullet points) could improve readability.

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

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

Without an output schema, the description thoroughly explains the return structure (summary block, per-advisory detail, links, alternative versions) and handles edge cases like partial failures and default version. Complete for a two-parameter 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%, but the description adds value: for 'package' it clarifies scoped packages are accepted; for 'version' it states defaults to latest. This exceeds 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 it is a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. It lists specific attributes (license, advisories, bundle size, etc.) and explicitly differentiates from sibling tools by focusing on npm ecosystem.

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 whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also clarifies scope (NPM only) and alternative for other ecosystems, and notes graceful degradation on partial failures.

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 hints (readOnlyHint, idempotentHint, etc.). The description adds valuable behavioral details such as embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K), and truncation behavior, which go 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 two sentences, front-loaded with key information, and contains no extraneous words. Every sentence adds value.

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

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

Despite no output schema, the description fully explains the return format (top-N passages with offsets and scores) and the verification use case. It is complete for this tool's complexity.

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

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

Schema coverage is 100%, yet the description adds meaningful context: examples for query, max char limit for text, and range/default for limit. This enhances understanding beyond the schema alone.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verb 'search' and resource 'source'. It distinguishes from siblings 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?

The description explicitly advises use when 'the record is too big to cram into the prompt' and mentions integration with ask_pipeworx_grounded. While it doesn't explicitly state when not to use, the context provides clear guidance.

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

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

The description adds significant behavioral context beyond annotations: returns subscription ID, delivery constraints (phone verification, SMS cap, webhook HMAC signing and auto-disable after failures), and idempotency not discussed but annotation indicates true. No contradiction with annotations (readOnlyHint=false is consistent with mutation).

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

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

The description is detailed (approx. 300 words) but every sentence adds value. Structure is logical: purpose, prerequisites, types with examples, delivery options with constraints. No redundancy or fluff.

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

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

For a tool with 3 parameters (including nested objects) and no output schema, the description is highly complete. It covers return value, prerequisites, type-specific param details, delivery options with edge cases (webhook disabled after 10 failures), and security (HMAC signing).

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning: explains each type's params with examples (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id) and delivery channel properties with constraints (phone verification, email pattern, webhook HMAC). This far exceeds baseline.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying it is for creating subscriptions. The verb 'subscribe' is specific and matches the 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?

The description explicitly requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It lists supported types with examples and explains delivery channels with constraints (phone verification, 10/day cap, webhook auto-disable). While it does not directly compare to alternatives, the context is clear for a creation tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: that it returns example questions with exact tool and argument shapes, drawn from a live catalog, and that calling with no arguments gives a full spread. 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 longer than average but every sentence provides necessary context. It is front-loaded with common user questions, then details the output and parameter. No irrelevant content given the tool's onboarding purpose.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all relevant aspects: purpose, when to use, parameter guidance, and output content. Annotations are comprehensive, so no gaps remain.

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

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

Schema coverage is 100%, but the description adds value by enumerating the specific topic values ('finance', 'pharma', etc.) that are not in the schema (no enums). It also explains the behavior when the parameter is omitted versus provided, which is not in 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 specifies the tool's purpose as an onboarding entry point that returns category-bucketed example questions. It uses a specific verb ('returns') and resource ('example questions'), and distinguishes from siblings like ask_pipeworx and discover_tools by noting it's for 'getting started' and for agents that 'do not yet know what Pipeworx can do'.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides guidance on the `topic` parameter to focus the results, implying when not to use (if topic is known) and giving alternatives via the tool catalog.

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 explains beyond annotations: row is deactivated not deleted, historical events stay available. This adds valuable info consistent with idempotentHint and destructiveHint. 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?

Three concise sentences, front-loaded with the primary action. No wasted words, well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, side effects, and integration with recent_alerts. Fully 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%, and the description does not add meaning beyond the schema. The parameter 'id' is clearly described in schema as a uuid from subscribe.

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

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

The description clearly states the tool cancels a subscription by id, with ownership enforcement and deactivation behavior. It distinguishes from the sibling 'subscribe' but doesn't explicitly differentiate from 'list_subscriptions' or 'recent_alerts'.

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

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

The description explicitly states ownership enforcement, guiding users that they can only cancel their own subscriptions. It doesn't mention when not to use or alternatives, but the context is clear.

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

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

The description goes well beyond annotations by explaining the verdict semantics, especially the critical caveat that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also discloses the routing logic, the use of live sources, verbatim evidence, and the exact output components. This is valuable context not available in the readOnly/idempotent annotations, and there is no contradiction between the description and 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 information-dense yet well-organized: it front-loads trigger phrases and purpose, then explains the dual pipeline, output format, and a crucial caller warning. Every sentence contributes new information without redundancy. The length is justified by the tool's complexity.

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

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

With no output schema, the description takes on the burden of explaining return values and does so thoroughly: it lists all possible verdicts, mentions the citation and reasoning, and clarifies the difference between 'could_not_verify' and 'unsupported'. It also covers the internal process and error semantics, making the description complete for a complex tool.

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

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

The input schema fully documents both parameters with examples and detailed semantics (100% coverage). The description adds only a passing reference to 'exact percent-delta math' relative to tolerance but does not substantially enrich the schema-provided meaning. Therefore, the baseline for high schema coverage is the correct score.

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 a natural-language claim verification service with explicit triggering phrases ('fact check', 'verify the claim'). It states the core verb+resource ('verify claim against authoritative sources') and distinguishes it from siblings by framing it as a fact-checker rather than a general Q&A or data-retrieval tool. The addition of 'Replaces 4–6 sequential calls' reinforces its unique 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?

It provides a clear when-to-use condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between financial claims (SEC EDGAR fast path) and other claims (grounded pipeline). However, it does not explicitly name alternatives or state when-not-to-use cases, which keeps it a step below a perfect score.

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