Blockstream Info

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns chain and mempool stats, providing some context beyond annotations, but does not detail any other behavioral traits like error handling or data freshness.

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 at one sentence, but it sacrifices necessary detail. It is efficient but not sufficiently informative for an AI agent to use correctly.

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 existence of sibling tools like 'address_txs' and the presence of an output schema, the description is too minimal to provide complete guidance. It does not explain what 'summary' includes, how it differs from other address-related tools, or what to expect in the output.

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

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

Schema coverage is 0%, meaning no parameter descriptions. The description does not mention the parameters at all, not even to clarify expected format or valid values for 'address' or 'network'. The examples in the schema help but are not part of the 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 'Address summary (chain + mempool stats)' clearly indicates it returns summary information about an address, distinguishing it from sibling 'address_txs' which likely returns transactions. However, it lacks a verb like 'get' or 'retrieve', making it slightly less explicit.

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. No mention of prerequisites, such as needing a valid address, or when to prefer it over 'address_txs' or other tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds context that results include mempool and confirmed transactions, which is useful beyond what annotations provide.

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

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

The description is a single, efficient sentence that directly states the tool's purpose. 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?

For a simple tool with few parameters and an output schema, the description covers the essential purpose. Could mention the scope (recent) but overall adequate.

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

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

Schema description coverage is 0%, and the description does not explain the 'address' or 'network' parameters beyond their names. The parameters are simple but the description adds no additional meaning.

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

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

The description clearly states the tool gets recent transactions for an address, including mempool and confirmed. It uses specific verb+resource ('Recent transactions for an address') and distinguishes from siblings like 'address' and 'transaction'.

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

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

The description implies usage for fetching recent transactions but does not explicitly state when to use this versus alternatives like 'transaction' or 'tx_status'. No exclusions or guidance on 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 adds significant behavioral context beyond annotations: it probes multiple LLMs, scores visibility, uses a default free model, and requires BYO key for Anthropic with direct payment. It also explains the return structure. No contradiction with annotations.

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

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

The description is concise, with 4 sentences. It front-loads the core purpose and then provides details on parameters and use cases. No unnecessary words.

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

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

Despite no output schema, the description details the return format per model and combined view. All parameters are covered. The tool is moderately complex but the description provides complete context for an agent to use 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%, but the description adds value: it explains the default model for 'models', that _apiKey is only needed for Anthropic, and that context helps disambiguate. This goes beyond the schema descriptions.

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

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

The description clearly states it probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It specifies the default model and optional Anthropic with BYO key. This distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use _apiKey and models parameter. While it doesn't explicitly say when not to use, the context makes it 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 reveals key behaviors: routes to one of 4,482 tools, fills arguments automatically, returns structured answers with citation URIs, and describes itself as a 'one fast call'. This adds value beyond annotations (readOnlyHint, idempotentHint) that already indicate safety and idempotency. 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 comprehensive but slightly verbose (150+ words). However, it is well-structured: starts with a strong directive, then provides examples, boundaries, and fallback guidance. Every sentence adds value, though some pruning could improve conciseness.

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

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

Given the tool's complexity (many sibling tools, broad domain coverage), the description is complete. It covers what it does, when to use it, examples, and how it differs from alternatives. No output schema exists, but the description adequately explains return values (structured answer with citation URIs).

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 6 parameters are aliases for the same 'question' field, and the schema descriptions already explain this clearly. The description does not add new semantic information about parameters beyond the schema's 100% coverage. 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 tool's purpose: answering factual questions using structured data from over 4,000 sources. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each, and provides a broad list of domains it covers.

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

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

Explicitly recommends 'PREFER OVER WEB SEARCH' for factual questions, and tells users to 'START HERE for most questions'. It also specifies when to step up to alternative tools (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). Examples illustrate 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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses several behavioral traits: refusal reasons (enumeration), cost of an extra LLM call, extraction logic from tool results only, and explicit refusal modes. This adds significant 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 well-structured with each sentence adding value: purpose, behavior, usage, cost trade-off. While slightly lengthy, it avoids redundancy and is front-loaded with the key differentiator. One minor improvement could be condensing the alias list since schema already covers it, but overall efficient.

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

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

Despite lacking an output schema, the description provides a detailed return structure including fields like 'answer', 'evidence', 'confidence', 'source', 'fetched_at', and explicit refusal reasons. This covers error handling and return format comprehensively, making it complete for a read-only tool with open world 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 description coverage is 100% as all parameters are aliases for 'question' and already described in the schema. The description adds the note 'Your question in natural language' which is clear but does not provide additional semantic depth beyond the schema. 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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from the sibling tool 'ask_pipeworx' by specifying its intended use for scenarios where answers must be verified and not invented. The verb 'ask' combined with 'grounded' conveys the core functionality.

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

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

Explicitly provides usage guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and advises to prefer the sibling tool 'ask_pipeworx' for casual lookups. This clearly delineates contexts where this tool should and should not be used.

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 patterns, response shapes, resolver contract, parent event extraction, news fields with fallback details, safety mechanisms (low-confidence short-circuit, closed markets, wide spreads), and resolution-rule risk. Annotations already indicate read-only, idempotent, open-world; the description adds deep operational context critical for correct agent behavior.

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

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

The description is long but well-structured with clear headings and bullet points. It front-loads purpose and usage, then details fan-outs, response shapes, and edge cases. Every section adds value given the tool's complexity. It could be slightly more concise, but the structure makes it navigable.

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 (large fan-out, multiple edge cases, no output schema), the description is remarkably complete. It covers match confidence, parent events, news fallbacks, safety blocks, resolution rules, and tradeability warnings. An agent can confidently invoke this tool with the provided information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it repeats parameter descriptions from the schema (depth, include_raw) but adds a detail about response size (20KB) for include_raw. Overall, it does not significantly enhance understanding of parameters 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 tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and key actions (resolve, classify, fan-out, return evidence). This is highly specific and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains input types (slug, URL, question text). However, it does not explicitly state when NOT to use or compare with sibling tools, leaving room for improvement. Nonetheless, 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 and destructiveHint=false, indicating a safe read operation. The description reinforces that it is a lookup tool, but adds minimal behavioral detail beyond the input format. 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 extremely concise at 7 words in one sentence, with no redundant information. It front-loads the core purpose and input constraints, 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?

Given the low complexity (2 params, simple retrieval), the description is nearly complete but omits the optional network parameter, which is only visible in the schema. The existence of an output schema reduces the need to describe return values. Overall, minimally adequate, but a brief mention of the optional parameter would improve completeness.

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

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

The description adds '64-char hex' specificity for the hash_or_height parameter, which the schema only describes as 'hex or numeric height'. This is useful clarification. However, the optional network parameter is not mentioned in the description, and schema coverage is 50%, so the description only partially compensates.

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 by 64-char hex hash or by height' clearly indicates the tool retrieves a block using either a hash or height. It is succinct and distinguishes from sibling tools like 'transaction' or 'address', though it could be improved by using an explicit verb like 'Get'.

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 guides usage by specifying valid input formats (64-char hex hash or height), but does not provide explicit when-to-use guidance or exclude alternatives. Sibling tools are distinct enough that context makes usage clear, but no direct comparisons are given.

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=true, idempotentHint=true) are consistent; description adds details like data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and return of citation URIs. No contradictions.

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

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

Description is slightly long but very efficient, front-loaded with trigger phrases. Every sentence adds value, covering triggers, usage, data sources, and output. Minor reduction possible but not penalizing much.

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 moderate complexity (two entity types, multiple data sources), description covers purpose, triggers, data sources, output behavior (paired data + citation URIs), and efficiency gains. No missing critical context despite no output schema.

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

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

Schema coverage is 100%; description adds meaning: type enum explained (company vs drug), values parameter with examples (tickers/CIKs, drug names) and constraints (2-5 items). Exceeds schema detail.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with trigger phrases like 'compare X and Y' etc. It distinguishes from siblings by explicitly stating it replaces 8-15 sequential lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It clearly specifies when to use (comparing entities) and what alternatives it replaces. No ambiguity.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals account requirements (free/paid), mechanism (decomposes question into facets, routes to 4,482 tools in parallel), return format (findings packet with evidence, confidence, source, citation, gaps[]), latency, and that it never invents. 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 long but every sentence adds necessary information. It front-loads the critical account requirement and alternative tool. The structure flows logically: prerequisites -> what it does -> how it works -> when to use -> limitations. Could be slightly more concise, but effective.

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

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

Given the complexity and lack of output schema, the description is remarkably complete. It covers return format, latency, data sources, limitations (not for breaking news), and differentiates from all listed sibling tools. An agent can reliably decide when and how to invoke this tool based on this description alone.

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 with good coverage (100%). The description adds value by explaining the depth enum in terms of number of facets (quick=3, standard=5, thorough=8) and emphasizing that broad/multi-part questions are suitable, 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 uses specific language: 'Grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded. It clearly states what it does (one-call multi-facet research) and what it is not (not open-web search).

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 provides when to use this tool versus alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and advises using ask_pipeworx if not signed in. It also gives example use cases and warns about latency (15-60s).

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 value by explaining that each result is 'ready to call directly, no second schema lookup needed.' This behavioral detail goes beyond annotations.

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

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

The description is informative and well-structured, starting with the core purpose. It is slightly verbose but each sentence adds value, and it is front-loaded with the most important information.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, full schemas, and curated examples). It provides a complete picture for an agent to understand the tool's functionality.

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 does not add additional meaning beyond what the schema provides for parameters like 'query' and 'limit.' The schema itself is sufficiently descriptive.

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: 'Find tools by describing the data or task.' It lists numerous domains and explains that it returns the top-N most relevant tools with schemas, making it distinct from sibling tools that are specific data sources.

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 to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the tool, though it does not explicitly mention when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint all true; description reinforces non-destructive nature and adds critical context: patents API may soft-fail due to sunset (PatentsView API). This goes beyond annotations. 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?

Description is dense and informative but slightly long (multiple sentences). However, it is front-loaded with examples and structured with sections for each data source. Loses one point for not being more terse, but still clear.

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

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

With only 2 simple parameters, no output schema, the description thoroughly explains what the tool returns (cik, company_name, recent_filings with URIs, fundamentals sorted, patents with caveat, news via GDELT→GNews, LEI via GLEIF). Agent has all needed context to invoke and interpret results.

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

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

Schema coverage is 100% (both parameters described). Description adds value by explaining 'type' is currently limited to 'company', 'value' accepts ticker or zero-padded CIK, and explicitly states names are not supported—clarifying parameter usage beyond schema constraints.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') and explicitly states it produces a full cross-source profile of US public companies. It lists all integrated data sources and returned fields, making the tool's purpose unmistakable and distinct from sibling tools like 'resolve_entity'.

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

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

Description gives clear when-to-use instruction: 'ALWAYS PREFER over chaining single-pack... lookups' for holistic views. Also specifies what not to do: names not supported, and directs to 'resolve_entity first if you only have a name'. This proactively prevents misuse.

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 little behavioral context beyond 'recommended sat/vB by confirmation target'. Open-world hint implies outputs may change, but this is not stated.

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 with no waste, but it is overly terse and omits important information about parameters.

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 an output schema likely present, the description fails to explain how 'confirmation target' is conveyed (no input parameter) and what the 'network' parameter does. Incomplete for effective use.

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

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

Schema coverage is 0% and the description does not explain the 'network' parameter. The example shows 'mainnet' but there's no description of valid values or how the parameter affects output.

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 'Recommended sat/vB by confirmation target' clearly states the tool provides fee rates, but doesn't specify what confirmation targets are available or how they are input. The title and name reinforce the purpose.

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

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

No guidance on when to use this tool vs alternatives like 'mempool', which might also provide fee data. The description lacks context for selection.

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

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

Description's 'Delete' aligns with annotations (destructiveHint: true, readOnlyHint: false). Adds context about clearing sensitive data. No contradiction; annotations already cover safety profile, description adds minor value.

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

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

Two sentences, front-loaded with core action, no wasted words. Efficient and clear.

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

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

Tool is simple (1 param, no output schema). Description covers purpose, usage context, and related tools completely given the low complexity.

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

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

Schema coverage is 100% and parameter 'key' is well-described in the schema. Description does not add additional parameter-level semantics 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?

Description clearly states 'Delete a previously stored memory by key.' Uses specific verb (delete) and resource (memory), and distinguishes from siblings by naming '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?

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

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

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

Annotations already indicate safe, idempotent, read-only behavior. Description adds valuable context: fetches page, extracts title/description/key links, emits standard markdown format, and outputs a single text blob. No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words. Each sentence adds value: what it does, how it works, when to use it.

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 only two parameters, no output schema, and rich annotations, the description is fully adequate. It covers the tool's purpose, behavior, and parameter specifics without 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% with descriptions for both parameters. Description adds practical details like max_links default of 25 and max of 50, which helps the agent set appropriate values.

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 generates an llms.txt file for any URL, specifying the output format and use cases. It distinguishes itself from siblings by being the only tool with this specific function.

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 are provided (getting client site indexed, drafting for own project, auditing competitor). While it doesn't explicitly state when not to use it, the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the scope of returning only the caller's subscriptions and lists specific return fields. It does not contradict annotations. It could mention pagination or rate limits, but given annotations, this is sufficient.

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

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

Two concise sentences: first defines purpose and return fields, second provides usage guidance. No redundant or extraneous information. Efficiently front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose, return fields, and usage context. Annotations cover safety, 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 description coverage is 100% for the single parameter include_inactive, which is already well-described in the schema. The description does not add any additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count), which is a specific verb+resource description that distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicitly excludes alternative actions like subscribing or unsubscribing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal value beyond stating the output, which aligns with the annotations. 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?

Extremely concise at three words, which is efficient for a simple tool. However, it could be more informative without becoming 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?

The presence of an output schema reduces the need to describe return values. However, the parameter is unexplained, and for a tool with one optional parameter, more context is needed to ensure correct invocation.

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

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

The single 'network' parameter has 0% description coverage in the schema, and the tool description does not clarify its meaning, valid values, or default behavior. The example shows 'mainnet' but the agent needs explicit guidance.

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 'Mempool size + fee histogram' clearly indicates the resource and the output components (size and histogram). It distinguishes from siblings like 'fee_estimates' and 'tip_height' by focusing on mempool state, though it does not explicitly state the action (e.g., 'get').

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 'fee_estimates' or 'tip_height'. The description lacks any context for usage scenarios or 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 provides valuable behavioral context beyond annotations: it's free, doesn't count against tool-call quota, rate-limited to 5 per identifier per day, and that the team reads digests daily. There is 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?

Every sentence serves a purpose, front-loaded with core intent, and details like usage, constraints, and internal info are efficiently packed. 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 feedback tool with 3 parameters and no output schema needed, the description covers all necessary context: purpose, when to use, what to include, constraints. It is 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%, so baseline is 3. The description adds meaning by explaining the purpose of each parameter (e.g., type enum values, message format) and clarifying optional context fields. This elevates it 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 clearly states the tool is for sending feedback about bugs, feature requests, or praise to the Pipeworx team. It uses specific verbs like 'tell' and 'broken, missing, or needs to exist', and distinguishes itself from siblings as the only feedback tool.

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

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

The description explicitly tells when to use the tool (bug, feature/data_gap, praise) and gives concrete instructions such as 'don't paste the end-user's prompt' and 'describe in terms of Pipeworx tools/packs'. It also mentions rate limits and quota.

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, openWorld, idempotent, non-destructive. Description adds that data is self-aggregating, derived from CF analytics-engine, no PII, and cached 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?

Two sentences plus a bullet list. Front-loaded purpose, then usage guidance and details. Every sentence adds value, no redundancy.

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

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

Covers inputs, usage, and caching. Lacks detailed output format but mentions the returned items (top tools, packs, volume). Given simplicity, it is fairly complete.

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

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

Schema already describes the window parameter well (100% coverage). Description adds context on how different windows surface trends vs steady-state, enhancing meaning beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like discover_tools by focusing on trending data rather than general 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?

Provides three explicit use cases and notes caching behavior. Lacks explicit 'when not to use' but gives clear context for when it is appropriate.

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

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

Discloses detailed behavioral traits beyond annotations: requires one parameter, explains partition check, semantic anchor for cross-event, placeholder filtering, fill check with live CLOB depth. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, no destruction).

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 lengthy; it front-loads the requirement and organizes information clearly, though some sentences could be more concise.

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

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

Given the tool's complexity, 2 parameters, and no output schema, the description thoroughly covers inputs, modes, filtering, expected response structure, and trade recommendations. Complete for an arbitrage detection 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 description adds significant value with usage examples, URL acceptance, and context for each parameter. Baseline 3, credit for extra guidance.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic), provides concrete examples, and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly guides when to use event vs topic mode, warns that no arguments fail, recommends event for specific markets, and advises against trading when realizable_edge_pp ≤ 0. Also mentions alternative tool for custom sizing.

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

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

The description discloses behavioral traits beyond the annotations: caching (1h at KV level), how empty segments are explained via diagnostics, the effect of knobs on filtering, and the detailed model logic. Annotations already mark read-only/idempotent; the description adds significant operational depth.

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 (model families, response top-level, tradeable-edge knobs). It is front-loaded with purpose and each detail serves a purpose for understanding the complex tool. Could be slightly more concise, but appropriate for the complexity.

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

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

Given no output schema and 9 parameters, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics), edge logic, caching, and all knobs. It addresses edge cases like Fed bets and threshold relaxation, making it complete for an agent to use effectively.

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

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

Schema coverage is 100% with each parameter having a description. The tool description adds context beyond the schema, e.g., explaining why min_partition_leg_kelly exists (partition arbs return 0 Kelly at parent level) and the rationale for slippage. This extra value lifts it above baseline 3.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly linking to the use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on edge detection via model families rather than pure arbitrage.

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 indicates when to use ('what should I bet on today') and explains the tradeable-edge knobs, but does not explicitly mention when not to use or directly compare with sibling tools. However, it provides enough context for an agent to decide.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds useful behavioral context: decay numbers come from daily closes (not intraday), history is bounded by 60-day TTL, and gaps indicate no scan occurred.

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 quite long but well-structured: it starts with purpose, then arguments, then response fields, then limits. Every sentence adds value; no wasted words.

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

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

Despite having no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) including field meanings like trend and decay_pp_per_day. It also covers limits and edge cases, making it 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 coverage is 100%, but the description adds meaning beyond the schema: it explains the lookback window ('max 30'), the snapshot family concept, and that snapshots are written on cache-miss. This extra context helps the agent understand parameter usage.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from polymarket_edges snapshots. It gives a concrete example contrasting fresh and old edges, and distinguishes this from sibling tools like polymarket_edges by focusing on historical persistence.

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

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

The description explains that the tool answers 'how long has this edge existed and is it shrinking?', which implies when to use it. It does not explicitly mention when not to use or name alternative tools, but the context makes the usage clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds rich behavioral detail: it explains the ladder-walking process, the return structure (top_of_book, vwap_fill_price, slippage, verdict), the auto-detection of side for baskets, and the risk of forced directional risk. No contradictions with annotations.

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

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

The description is detailed and well-structured, with a clear summary first, followed by explicit mode sections and usage guidance. While every sentence adds value, the length could be slightly reduced without losing clarity. However, for a complex tool with no output schema, the verbosity is justified.

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 modes, multiple return fields, no output schema), the description is remarkably complete. It explains return values for both modes, the verdict system, the clamp on size_usd, and the risk of directional exposure. An agent can fully understand the tool's behavior without additional documentation.

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

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

Schema coverage is 100%, but the description adds critical meaning: it clarifies that exactly one of market or event is required, explains the side default and auto-mode for baskets, and distinguishes size_usd interpretation (maximum spend on buys vs target proceeds on sells for single-market; settlement notional for baskets). 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 opens with a clear verb-resource pair ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and immediately distinguishes two modes (single-market and basket). It explicitly ties usage to sibling tools (polymarket_arbitrage, polymarket_edges), making its unique role unmistakable.

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

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

The tool explicitly states when to use it ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and covers both modes with clear prerequisites (market slug for single, event slug for basket). It also warns against partial basket fills, which is a critical usage caveat.

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

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

Goes far beyond annotations. Discloses safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and explains their meaning in detail. Explains what happens when bet shapes are non-equivalent or events don't match. No contradiction with readOnlyHint/openWorldHint/idempotentHint/destructiveHint.

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

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

The description is lengthy (over 200 words) but every sentence adds crucial information. It is well-structured with sections for modes, response, and safety fields. Could be slightly more concise, but not wasteful.

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

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

Despite no output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spread array with top_spreads_pp, and safety fields. Covers edge cases like compatibility_warning in two scenarios and temporal_alignment. Fully prepares the agent for correct invocation and interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the auto-fetch behavior for topic and override semantics for explicit parameters. Examples in input schema also help.

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: compute cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage which focus on single-venue opportunities. The verb 'spread' and resource 'cross-venue' are specific and unambiguous.

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

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

Provides explicit guidance: two modes (topic for pre-mapped macros, explicit tickers for custom pairings). Warns that most pre-mapped topics return compatibility_warning, setting realistic expectations. Implicitly advises against using when temporal alignment is false or events are semantically unrelated.

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, non-destructive. Description adds scoping to identifier and behavior of omitting key (lists all). No contradictions.

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

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

Three concise sentences, front-loaded with main action. No wasted words, 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?

For a simple one-parameter tool with no output schema, description covers retrieval, listing, scoping, and complementary tools. Complete for its complexity.

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

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

Only one optional parameter 'key' with 100% schema coverage. Description adds meaning by explaining omission lists all keys, clarifying optional behavior 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 retrieves a value by key or lists all keys, with specific verb 'Retrieve' and resource 'value' or 'keys'. Distinguished from sibling tools 'remember' and 'forget'.

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

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

Provides explicit use case: to look up stored context without re-deriving. Mentions scoping and pairing with remember/forget. No exclusion criteria, 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are augmented by the description: it explains the mark_read flag's effect on state, the event's fields, and that polling works fine. No contradictions; the description adds valuable 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: purpose, return fields, filter options, then alternative access. Every sentence adds value with minimal redundancy. Slightly verbose compared to a terse alternative, but still efficient.

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

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

Given 5 optional parameters, no output schema, and rich annotations, the description covers return content, filtering, and state modification (mark_read). It also mentions the REST endpoint for alternative use. Could mention error handling or rate limits, but sufficient for a read-only 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 meaning: examples like 'sec_8k' for type, clarifies ISO timestamp for since, and explains mark_read's effect on subsequent calls. This goes beyond the schema's property 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: 'Pull fired events from your subscription feed.' It specifies the content returned (source, citation_uri, raw payload) and filtering options. While it doesn't explicitly distinguish from all siblings, it is specific enough (verb+resource+scope) and mentions an alternative REST endpoint, aiding differentiation.

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

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

The description provides clear usage context: filtering by type/since, setting mark_read, and polling. It mentions an alternative access method ('same feed at GET registry.pipeworx.io/alerts.json for scripts and dashboards'), guiding when to use this tool vs. scripting. However, it doesn't explicitly state when not to use or compare with other sibling tools like list_subscriptions.

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, idempotent, non-destructive. Description adds: source fan-out logic, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, output structure with grouped changes and citations.

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 and well-structured with examples upfront, but slightly lengthy. Could be trimmed without losing clarity.

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

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

Given no output schema and high complexity (multiple sources, fallback, relative dates), description covers input formats, source behaviors, output structure, and alternative tool. Includes note about PatentsView API sunset.

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 significantly enhances meaning: explains `since` accepts ISO or relative shorthand with examples, `type` is only 'company', `value` accepts ticker or CIK. Provides usage recommendation for `since`.

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 the tool provides a change feed for a company by fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives concrete example queries and distinguishes from sibling tool entity_profile.

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

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

Provides explicit when-to-use (monitoring recent changes) and when-not-to-use (use entity_profile for static profile). Also explains source fallback behavior and recommends typical `since` values.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; description adds key details: scoped by identifier, persistence for authenticated users vs 24-hour retention for anonymous, and pairing with recall/forget.

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 four sentences, front-loaded with purpose, each sentence serves a distinct purpose: purpose, usage, storage behavior, companion tools. 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?

For a simple tool with 2 params and no output schema, the description covers all necessary aspects: purpose, usage, storage details, and interactions with sibling 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?

Schema coverage is 100%, so baseline is 3. Description adds minimal extra meaning beyond schema (e.g., example key conventions), but doesn't significantly enhance 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 uses a clear verb 'save' and resource 'data', specifies scope 'across this conversation or across sessions', and distinguishes from siblings by mentioning companion tools 'recall' and 'forget'.

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

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

The description explicitly tells when to use ('when you discover something worth carrying forward'), but lacks explicit when-not-to-use guidance, though it's implicitly clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which gives extra behavioral insight 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?

The description is somewhat long but well-structured: it starts with example queries, states the primary use case, then details supported types. Every sentence adds necessary information, though minor trimming could improve conciseness.

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

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

Given the tool's complexity with two entity types and no output schema, the description fully explains what each type returns (ticker+CIK+company_name+URI for company; RxCUI+ingredient+brand+URI for drug), including citation URIs. This is sufficient for an agent to understand inputs and expected outputs.

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 both parameters. The description adds value by giving concrete examples for 'value' (e.g., ticker, CIK, name for company; brand/generic for drug) and mentioning auto-disambiguation for company input, going beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, lists example queries ('What's the ticker for...', 'find the CIK for...'), and distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing a clear usage context. It also lists supported types and their expected outputs, though it doesn't explicitly state when not to use 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. Does not contradict annotations.

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

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

Two sentences, no wasted words. First sentence states core action and output; second provides use case. Front-loaded with key information.

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

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

No output schema but description specifies return format: ranked list with score, confidence, signal density. Parameters fully documented. Complexity is moderate and description covers all necessary context for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for all 4 parameters. Description adds beyond schema: treats first entity as 'subject' for narrative, rest competitors. For models, it repeats schema info. Overall adds value for entities parameter.

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

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

Description clearly states verb 'compare' and resource 'AI visibility across multiple entities'. It specifies the action (probes with ai_visibility_check, ranks by score) and differentiates from sibling ai_visibility_check which is for single entities.

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

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

Provides explicit use case 'competitive AI-marketing audits' with an example question. Does not explicitly state when not to use, but the context is clear. References ai_visibility_check as the building block, implying alternative for single probe.

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 read-only, idempotent, non-destructive hints. The description adds valuable behavioral context about partial failures and timing: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns'. 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 relatively long but packed with essential information. It front-loads the main purpose and then details behaviors and limitations. Could be slightly more concise, but appropriate for the complexity.

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

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

Despite no output schema, the description thoroughly explains return fields (summary block, per-advisory detail, links, recent alternatives) and ecosystem limitations. Covers partial failures and timing, making it complete for agent use.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds a little value by clarifying scoped packages ('@types/node') and default version behavior, but mostly repeats what the schema already says.

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 'composite should I add this npm package to my project check in ONE call' and details the sources and information gathered. It distinguishes from siblings by explicitly noting 'NPM ecosystem only in v1' and directing to deps.dev:version for other ecosystems.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals key behavioral details: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character cap (200K chars), and that results include character offsets for verification. It does not contradict any annotations.

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

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

The description is well-structured with a clear opening sentence, followed by usage context and technical details. It is front-loaded with the core purpose. While slightly verbose with example lists, it remains efficient and earns its sentences.

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

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

Despite lacking an output schema, the description covers return values ('top-N passages with character offsets and similarity scores'), input constraints (200K char cap), and a pairing suggestion with another tool. It is complete enough for an agent to understand how to use and interpret results.

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

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

Schema coverage is 100% for the 3 parameters, so the baseline is 3. The description adds little beyond the schema: it restates the text and query descriptions almost verbatim, and the limit parameter is fully described in the schema. No additional semantic nuance is provided in the description.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It uses specific verbs and resources, and gives concrete examples (SEC 10-K, article). It also distinguishes from siblings by mentioning its pairing with 'ask_pipeworx_grounded', making it clear when to use this tool over alternatives.

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

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

The description explicitly tells when to use the tool: 'when the record is too big to cram into the prompt — search_within saves context.' It also provides a workflow: 'pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' This gives clear guidance on usage and alternatives.

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

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

Annotations indicate idempotentHint=true and readOnlyHint=false, but the description adds context such as OAuth requirement, delivery constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and webhook signing details. These go beyond annotations and disclose important behavioral traits.

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

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

The description is fairly long but well-structured: purpose first, then requirements, then types and delivery. Every sentence adds value, though minor redundancy (e.g., 'delivery' details repeated in both description and schema) could be tightened.

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

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

Given the moderate complexity (3 params, nested objects, enums, external dependencies), the description covers prerequisites, type-specific params, delivery options with constraints, and notes on webhook signing. No output schema, but the returned id and webhook secret are 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?

Schema coverage is 100%, but the description enriches each parameter with examples, constraints (e.g., phone must be verified, webhook HTTPS only), and explains type-specific param structures. This adds significant 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 clearly states it creates a subscription to a live-data event stream and returns a subscription ID. The verb 'Create' and resource 'proactive monitoring subscription' are specific, and it distinguishes from siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

The description specifies when to use (monitoring subscription), requirements (Pipeworx OAuth account, no anonymous/BYO), and provides examples of supported types. It does not explicitly state when not to use or name alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's burden is lower. It adds context about returning category-bucketed example questions and that it draws from the live catalog, enhancing transparency without contradictions.

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

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

The description is concise yet comprehensive, front-loading common queries and listing categories efficiently. 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it explains what the tool does, when to use it, and what it returns, including category enumeration.

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

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

Schema coverage is 100% with a description for topic, so baseline is 3. The description adds value by providing examples ('finance', 'pharma', 'betting') and listing the categories, exceeding schema-only info.

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

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

The description uses specific verb 'suggest' and resource 'questions', and clearly states it is the onboarding entry point for learning what Pipeworx can do. It distinguishes from sibling tools like ask_pipeworx and compare_entities by focusing on generating example questions.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also advises calling with no arguments for full spread or passing a topic for focus, providing clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond what annotations provide. It does not discuss rate limits, caching, or any side effects.

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 phrase) and front-loaded with the key information. It does not waste words, though it could be slightly more descriptive without losing conciseness.

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

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

Given the tool's simplicity (single optional parameter, output schema exists), the description is adequate. It covers the core purpose, and the annotations handle safety. However, it does not explain the return format or values, but that is covered by the output schema.

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

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

Schema coverage is 100% with one parameter 'network' already described in the schema. The description does not add any additional meaning or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it returns the current block height of the chain tip. It is specific about the resource (chain tip height) and implies the action (get). It distinguishes from sibling tools like 'block' which may 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?

No explicit guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, or when not to use it. The agent must infer usage from the description alone.

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 minimal extra context beyond that, only stating it retrieves 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?

The description is a single sentence, front-loading the core purpose. It is appropriately concise for a simple lookup tool.

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

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

Despite having an output schema, the description fails to explain the 'network' parameter. For a tool with two parameters, it is incomplete.

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

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

Schema description coverage is 0%, but the description only mentions 'txid' and not the optional 'network' parameter. This leaves meaning incomplete.

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 returns transaction details for a given txid. However, it does not differentiate from sibling tools like 'tx_status' which also deals with transactions.

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

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

No guidance on when to use this tool versus alternatives like 'tx_status' or 'address_txs'. It does not specify scenarios where this tool is appropriate or not.

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, idempotent, non-destructive. The description adds that it returns block_height, block_hash, confirmed, but does not disclose behavior for invalid txids or other edge cases. Adequate given 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?

One sentence, front-loaded with purpose and result fields. No unnecessary words. Highly efficient.

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

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

Given an output schema exists, the description does not need to detail return values. However, it omits explanation of the network parameter and edge cases (e.g., unconfirmed tx). Adequate but not 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 description coverage is 0%, so description must compensate. It mentions 'txid' implicitly but does not explain the 'network' parameter or provide format/constraints for either. Insufficient for 2 parameters.

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

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

The description clearly states it returns confirmation status (block_height, block_hash, confirmed) for a txid, which is a specific verb+resource. This distinguishes it from sibling tools like 'transaction' (full details) and 'block' (block info).

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 it is for checking confirmation status of a transaction, but does not explicitly state when to use it over alternatives like 'transaction' or 'address_txs'. No guidance on when not to use it.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds ownership enforcement and the soft-delete behavior (deactivated not deleted), which are useful beyond annotations. It does not cover error cases or side effects fully.

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

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

Two sentences, front-loaded with the main action. Every sentence adds value. No redundancy or fluff.

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

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

For a simple 1-parameter mutation tool without output schema, the description covers key aspects: action, ownership, and soft-delete. It lacks details on error handling (e.g., nonexistent or unauthorized id), but overall 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% with a clear description for the 'id' parameter. The description does not add extra semantics beyond what the schema already provides.

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

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

The description clearly states the action ('Cancel') and the resource ('a subscription by id'), with specific constraints ('Ownership is enforced'). It distinguishes from siblings like 'subscribe' (create) and 'list_subscriptions' (list).

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 context of use is implied: when you want to cancel a subscription. It mentions that historical events stay available via recent_alerts, hinting at an alternative. However, it lacks explicit when-not-to-use or direct comparison with other cancellation methods.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: returns verdict, structured form, actual value with citation, percent delta, and that it replaces multiple sequential calls. No contradictions.

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

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

The description is concise, front-loaded with trigger phrases and purpose, provides examples, and every sentence adds value without redundancy.

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

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

Given the complexity of claim verification, the description covers purpose, usage, scope, return type, and efficiency. No output schema exists, so the description adequately explains return values. Complete for this tool.

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

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

Schema coverage is 100% for the single parameter 'claim', and the tool description adds clarifying context about claim format and examples, going beyond the schema description.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It lists trigger phrases and distinguishes itself from general research tools by being specialized for verification.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the scope with 'v1 supports company-financial claims'. It implies limitations but does not explicitly state alternatives, though it notes efficiency gains over sequential calls.

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