Blockstream Info

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, providing comprehensive safety and behavior information. The description adds no additional behavioral context beyond stating it provides a 'summary'. It does not contradict the annotations, so a score of 3 is appropriate as the description adds minimal value beyond structured fields.

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

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

The description is very short and front-loaded, which is good for readability. However, it is so minimal that it sacrifices necessary content. For a tool with two parameters and an output schema, a slightly more detailed description would be warranted without being verbose. It earns a 3 because while concise, it is under-specified.

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, 0% schema coverage, and an output schema), the description is insufficient. It does not explain the return values or parameter details, leaving the agent with many unknowns. The description should provide more context to be complete.

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

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

With 0% schema description coverage, the description must compensate by explaining the parameters. However, it only mentions 'address' and 'network' implicitly through the examples. The description does not clarify the meaning of these parameters or their expected formats, leaving the agent without sufficient guidance to correctly invoke the tool.

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 identifies the tool's purpose: retrieving a summary of address data including chain and mempool statistics. It specifies both the verb 'summary' and the resource 'address', which is sufficiently distinct from sibling tools like 'address_txs' that focus on 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 is provided on when to use this tool versus alternatives. The sibling 'address_txs' suggests a related use case, but the description does not distinguish between them or inform the agent about appropriate scenarios for choosing this tool over others.

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 detail beyond the annotations by specifying the return fields (txid, inputs/outputs, fee, size, confirmation status) and coverage (mempool + confirmed). This helps manage expectations about output structure. It does not contradict the readOnlyHint, idempotentHint, or openWorldHint annotations, and the no-destructive hint is consistent. No need to discuss side effects for a read-only API.

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 reasonably concise, using three sentences that front-load the API source and then explain the output and intended use. The mention of 'Blockstream.info Esplora API' is slightly extraneous but provides context. No redundancy with the input schema is present, and the structure is logical.

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 read-only tool with an output schema present, the description covers return fields and the scope of results. However, it leaves out important details such as pagination limits, parameter constraints, and how to request testnet vs mainnet. These gaps matter for correct invocation, but the presence of the output schema reduces the burden on the description to explain all return values.

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

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

Schema description coverage is 0%, so the description must compensate. It only vaguely references the address and network ('one address', 'mainnet or testnet') without explaining accepted formats, defaults, or possible values. The 'network' parameter is especially ambiguous—does it accept 'mainnet'/'testnet' strings, or maybe 'btc'/'test'? The address format (P2PKH, P2SH, bech32) is not specified either.

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

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

The description clearly states the tool returns the most recent Bitcoin transactions for a single address, including both unconfirmed and confirmed entries. It explicitly distinguishes from related tools like 'address', 'transaction', and 'block' by focusing on address transaction history. The phrase 'Answers what this Bitcoin address has sent or received lately' reinforces the specific 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?

The description implies the tool is for retrieving recent transaction history for an address, and mentions support for mainnet/testnet. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions (e.g., not for full historical data, not for address balances). The context is clear but under-specified.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds context: returns per-model data with score, confidence, signals, raw_response, and combined view. Explains cost implications for Anthropic 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?

Two well-structured sentences that front-load the core purpose and key details. No redundant or unnecessary information; every sentence earns its place.

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

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

Given the tool has 4 well-documented parameters, no output schema, and no nested objects, the description covers all necessary aspects: input, configuration, return format, and use cases. Fully sufficient for correct invocation.

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

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

Schema description coverage is 100%, but description adds value beyond schema: explains default model, _apiKey purpose (BYO key), and context usage for disambiguation. Enhances understanding of parameter semantics.

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

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

The description clearly states the tool probes LLMs about entities and scores visibility (0-100) per model. It uses specific verbs ('probe', 'score') and identifies the resource (LLMs). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by specifying marketing audits and brand checks.

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

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

Provides explicit guidance on default model usage and how to use Anthropic with an API key. Implies when to use the tool (marketing audits, brand checks) but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond these: internal routing across 5,529 tools/1,455 sources, stable pipeworx:// citation URIs, and 'one fast call' performance. No contradictions; the bar is lower with annotations but the additions are valuable.

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

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

The description is longer than average but information-dense and well-structured. It front-loads the key directive ('PREFER OVER WEB SEARCH'), uses clear sections (domains, triggers, examples, alternatives), and every sentence contributes value. Not a 5 due to length.

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

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

Given the tool's complexity (routing to thousands of sources, no output schema), the description is highly complete. It covers return format, use cases, exclusions, and even addresses breaking-news nuance. An agent has all needed context 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?

The input schema fully documents all six parameters (aliases) with 100% coverage. The description does not add new parameter details beyond what the schema already states, though the examples illustrate usage. 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 defines the tool's purpose: answering factual questions about current/historical data by routing to thousands of sources and returning structured answers with citations. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its unique role obvious.

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

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

Provides explicit guidance on when to use versus alternatives: 'PREFER OVER WEB SEARCH', listed trigger phrases, concrete examples, and a clear step-up path to ask_pipeworx_grounded and deep_research. This is a model of usage instruction.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds valuable behavioral context: it is a live experimental router, currently has no active candidate (as of a specific date), and behaves identically to ask_pipeworx. It also clarifies it is a fully working router, not a fallback. This goes beyond the annotations without contradicting them.

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

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

The description is appropriately sized, front-loaded with the core identity, and every sentence contributes: it defines what it is, explains the experimental state, gives usage guidance, and removes ambiguity about fallback behavior. It is slightly long but all information is relevant and well-organized.

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

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

The description provides the essential context for a beta variant: relationship to ask_pipeworx (same tools, arguments, response shape), current experimental status, and usage intent. It does not detail the response format, but since it states 'same response shape' and the sibling ask_pipeworx exists, this is acceptable. The lack of an output schema is compensated by the reference to the stable counterpart.

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 provides 100% coverage, with all six params described as aliases for the required 'question'. The description only says 'same arguments' without adding any new semantics. Since the schema already fully documents the parameters, it meets the baseline but adds no extra value.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' and an 'identical universal router', establishing it as a query-routing tool. It also distinguishes itself from siblings by mentioning the same 5,529 tools and experimental routing, differentiating it from ask_pipeworx and ask_pipeworx_grounded.

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

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

The description explicitly provides when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router by noting results are compared to decide merges, which implies the stable version is for production. This gives clear usage context relative to alternatives.

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

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

The description goes far beyond the annotations. It discloses the refusal behavior with specific reason codes ('not_in_source','no_tool_match','tool_error','data_truncated','llm_error'), the evidence extraction mechanism, the extra LLM call cost, and the exact success output structure. This provides rich behavioral context about failure modes and reliability, which annotations alone do not convey.

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

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

The description is front-loaded with the core purpose, then details the routing/process, then the exact return format, then usage guidance and cost trade-off. Every sentence earns its place — there is no filler. The length is justified by the complexity of the tool's behavior and the need to distinguish it from ask_pipeworx.

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

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

With no output schema present, the description fully specifies return values on both success and refusal paths, including the exact refusal_reason enumerants. It also covers when to use vs. ask_pipeworx and the cost implication. For a tool with this complexity and no output schema, the description is complete and self-sufficient.

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

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

The input schema already fully describes all parameters (100% coverage) — six aliases for the same 'question' parameter. The description confirms that the question is in natural language and notes that the tool 'fills arguments,' but it adds no new parameter-level detail beyond the schema. The schema carries the heavy lifting, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource+mode: 'Hallucination-resistant answer mode for high-stakes reads.' It further distinguishes itself from sibling ask_pipeworx by explaining it EXTRACTS the answer using ONLY what the tool result contains, and explicitly states the return format. This is far beyond a vague or tautological 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?

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names when not to use it: 'prefer ask_pipeworx for casual lookups,' backed by the cost difference ('Costs one extra LLM call'). This directly addresses alternatives and exclusions.

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

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

The description extensively discloses behavioral traits beyond annotations: low-confidence resolutions short-circuit, closed markets skip fan-out, wide-spread markets carry illiquidity warnings, resolver contract details, parent event extraction, news fallback fields, and resolution-rule risk. It adds significant value beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). No contradiction.

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

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

The description is well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.) and front-loads the main purpose. However, it is quite verbose; some details could be condensed without losing value.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all aspects: input formats, fan-out behavior per bet category, response structure with detailed field explanations, safety mechanisms, resolution-rule risk, and edge cases. It is thoroughly complete.

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

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

Schema coverage is 100% and the description enriches each parameter: 'market' accepts slug, URL, or question text; 'depth' defaults to thorough with explanation; 'include_raw' defaults false with guidance on when to use true. Fan-out examples for various categories provide additional context for 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 researches Polymarket bets using Pipeworx data, specifying inputs (slug, URL, question text) and outputs (evidence packet, market-model comparison). It also provides usage examples like 'should I bet on X'. This is very specific and distinguishes its purpose from sibling tools like polymarket_edges.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes important guidance like inspecting market_match_confidence before trusting analysis. However, it does not explicitly state when not to use it or provide alternatives among siblings.

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

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

Annotations already provide safety hints (readOnly, idempotent, not destructive). The description adds that the tool accepts either a hash or height as input, which is useful. However, it does not disclose any additional behavioral traits such as the structure of the returned block data 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?

Extremely concise and front-loaded. Every word is meaningful. However, it might be too terse for some users, but it efficiently communicates the core functionality.

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

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

Given the presence of an output schema, the description does not need to explain return values. However, it omits mention of the optional 'network' parameter and does not provide enough context for a user to know when the tool is appropriate. It is adequate for a simple tool but lacks 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 clarifies the format of 'hash_or_height' beyond the schema (64-character hex), adding a small amount of meaning. The 'network' parameter is not mentioned. Schema description coverage is 50%, and the tool description 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 clearly states the tool retrieves a block by either a 64-character hex hash or by height. It uses a specific verb and resource, and the examples further clarify. However, it does not differentiate from sibling tools that may also return 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 guidance on when to use this tool versus alternatives. It does not mention any prerequisites, limitations, or when not to use it. The description is purely a statement of what it does.

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

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

The description adds behavioral context beyond annotations: it makes a parallel call, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. Annotations already provide readOnly/idempotent/etc., and description aligns 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?

The description is dense but every sentence adds value: front-loaded with examples, then specifics on data sources, sorting, and efficiency. No wasted words; appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description explains return format ('paired data + pipeworx:// citation URIs') and sorting. For a tool with two entity types, it covers all key aspects: data sources, parallel execution, and result structure.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining what data each type pulls (SEC EDGAR/XBRL for company, FAERS for drug) and that values are tickers or drug names, going beyond schema descriptions.

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

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

The description states the tool does side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and examples like 'X vs Y'. It clearly distinguishes from sibling tools like entity_profile and 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups', providing clear when-to-use guidance. It does not explicitly list when not to use, but context implies alternatives for single entity lookups.

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, and the description adds rich behavioral context: return packet components (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] array, contradictions[] for standard/thorough, hop field, citation resolvability, semantic excerpting, and expected latency. It also explains depth tiers' iterative behavior. No contradictions with annotations.

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

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

The description is information-dense but structured as one long paragraph without breaks, making it harder to scan. It front-loads critical constraints (account required, not open-web search) but includes many details (citation resolving, semantic excerpting) that could be trimmed or reorganized. Still, no sentence is wasted.

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

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

Even without an output schema, the description fully characterizes the tool's behavior and return value: findings packet fields, gaps[], contradictions[], hop, citation_uri, semantic excerpting, latency, account tiers. It covers prerequisites, alternatives, and edge-case behavior for news topics. This is comprehensive for a complex research tool.

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

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

Schema already documents both parameters with detailed descriptions (100% coverage), so baseline is 3. The description adds beyond the schema: 'thorough' requires a paid plan, standard/thorough re-angle gaps and add contradictions[] scanning, and 'Broad/multi-part is fine' clarifies question scope semantics.

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

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

The description states a specific verb and resource: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains that it decomposes questions into facets routed in parallel across 5,529 tools. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx for single lookups and news queries.

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

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

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and even provides examples. It names alternatives with clear reasons: 'For a single lookup use ask_pipeworx' and for breaking news 'prefer ask_pipeworx'. It also states an account prerequisite and that non-signed-in users should use ask_pipeworx.

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

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

Description adds value beyond annotations: explains that it returns top-N relevant tools with curated examples and requires no second schema lookup. Aligns with annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) and does not contradict them.

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

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

Description is front-loaded with the core purpose, followed by examples and usage guidance. It is slightly lengthy but every sentence contributes value, no filler. Could be more concise but still effective.

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

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

For a discovery tool, the description is complete: explains what it does, when to use, what it returns (names, descriptions, schemas), and even mentions curated examples. No output schema is needed as the description covers return value adequately.

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

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

Input schema covers 100% of parameters with descriptions. The description does not add semantic meaning beyond the schema; it merely restates that 'query' is natural language. Baseline 3 is appropriate given high coverage.

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

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

Description clearly states that the tool finds tools by describing data or task, with specific verb 'find' and resource 'tools'. It lists numerous domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that are specific to domains.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear context for use. No alternative tools or when-not-to-use are mentioned, but it highlights that results include full schemas, making them ready to call.

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 readOnlyHint=true, idempotentHint=true; description adds important limitations like USPTO PatentsView API sunset and soft-fail behavior, and explains data sources and return fields. No contradiction with annotations.

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

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

Well-structured with a list of returns and sources, but slightly verbose. Front-loaded with examples and core purpose; each sentence adds value.

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

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

Covers all necessary aspects: supported inputs, data sources, fallback behavior, limitations (patents sunset), and return fields. Although no output schema, the description adequately explains the return structure.

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

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

Schema coverage is 100% and description adds context beyond schema (e.g., 'Names not supported', 'use resolve_entity first'), explaining parameter constraints and usage nuances.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples and explicit preference over chaining single-pack lookups. It distinguishes from siblings by naming alternatives and declaring when to prefer this tool.

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

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

Explicitly states when to use (holistic view request) and when not to (names not supported, use resolve_entity first). Encourages preference over chaining lookups, providing clear guidance for the agent.

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 says 'by confirmation target' but the input schema has no 'target' parameter, only an optional 'network' string. This mismatch is confusing. Annotations (readOnly, openWorld, idempotent) are present but the description fails to clarify what the 'network' parameter does or how targets are specified.

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

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

The description is very concise (six words) but lacks essential details about inputs and behavior. It is front-loaded but incomplete, making it adequate but not helpful.

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 single optional parameter and 0% schema coverage, the description should provide more context about the 'network' parameter and how to interpret the output. The output schema exists but is not described. The description is incomplete for effective tool invocation.

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

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

Schema description coverage is 0% and the description does not explain the 'network' parameter at all. It mentions 'confirmation target' but that is not a parameter. No additional meaning is provided beyond the schema.

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

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

The description clearly states the tool provides recommended sat/vB fees by confirmation target, which is a specific and distinct resource. This distinguishes it from siblings like 'tip_height' (current block fee) and 'mempool' (mempool state).

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

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

Usage is implied from the name and description, but there is no explicit guidance on when to use this tool versus alternatives (e.g., 'mempool' for dynamic fee estimates). No when-not-to-use conditions are mentioned.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing stale or sensitive data, which goes beyond the annotations.

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

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

Two efficient sentences with no wasted words. The essential information is front-loaded: the action and key usage guidelines.

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

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

Given the simple schema (1 parameter, no output schema) and informative annotations, the description is complete. It covers purpose, usage, and pairing with related 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?

The input schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete.' The description merely says 'by key,' which adds minimal extra 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 'Delete a previously stored memory by key,' which is a specific verb+resource. It distinguishes the tool from siblings like 'remember' and 'recall.'

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

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

The description explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions alternatives/related tools: '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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable detail: it fetches the page, extracts title/description/key links, and emits the standard format. This explains the internal process beyond the annotations, though it could mention potential external dependencies or rate limits.

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

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

The description is concise at three sentences, front-loading the core purpose and then efficiently covering process and use cases. Every sentence adds value with no repetition or fluff.

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

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

Given no output schema, the description adequately describes the output as a single text blob ready for deployment. It covers input, process, output, and use cases. With 2 well-described parameters and clear behavioral context, the description is complete for the tool's complexity.

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

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

The input schema fully describes both parameters (url and max_links) with 100% coverage. The description does not add significant meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the output format (standard llms.txt markdown) and lists concrete use cases (indexing client sites, drafting for own project, auditing competitors), making the purpose immediately obvious and distinct from any sibling tools.

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

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

The description provides clear context by listing when it is useful (getting a client's site indexed, drafting for own project, auditing competitors). However, it does not explicitly state when not to use this tool or mention any alternatives among the sibling tools, which would improve guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the default behavior (returns active subscriptions) and listing the exact fields returned, providing context 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?

Two sentences with no wasted words. The first sentence states the action and return data, the second provides usage context. Perfectly concise and front-loaded.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It covers the action, return fields, usage guidance, and parameter behavior, all supported by comprehensive annotations.

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

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

The sole parameter 'include_inactive' is already fully described in the input schema (100% coverage). The description implies its effect by mentioning 'active subscriptions' but does not add new meaning, 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 name and title clearly state 'list_subscriptions' and the description explicitly says 'List the caller's active subscriptions', providing a specific verb and resource. It also lists the returned fields, distinguishing it from siblings 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?

The description guides when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe, unsubscribe), but lacks explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds no behavioral details. It does not mention data freshness, rate limits, or what exactly 'mempool size' and 'fee histogram' entail.

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

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

The description is extremely short at 4 words, which is concise but under-specified. It lacks crucial detail about the output format and parameter usage, making it minimally adequate.

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 parameter, output schema exists), the description still omits essential context like what 'mempool size' refers to (e.g., number of transactions, bytes) and how the histogram is structured. This leaves the agent with gaps in understanding.

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

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

The single parameter 'network' has 0% schema description coverage, and the description does not mention it at all. The agent gets no guidance on valid values or its effect. With low coverage, the description must compensate but fails to do so.

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

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

The description clearly states the tool returns 'mempool size + fee histogram', which is a specific verb (retrieve) and resource (mempool data). This distinguishes it from siblings like 'fee_estimates' and 'tip_height', which serve different purposes.

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, or any context regarding prerequisites or exclusions. The user must infer intent from the name 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?

With all annotations set to false, the description carries the full burden and does so thoroughly. It discloses the claim_token workflow, the ability to later check resolution status, the rate limit ('Rate-limited to 5 per identifier per day'), the cost ('Free'), and content rules ('don't paste the end-user's prompt'). These details give the agent an accurate model of side effects and asynchronous 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 every sentence earns its place by covering purpose, usage, exclusions, content guidance, token flow, rate limits, and cost. It is front-loaded with the core action and then layers details logically. While not as terse as some, the length is justified by the tool's complexity.

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

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

Given that there is no output schema, the description fully explains return behavior: it mentions that filing returns a claim_token, and that passing the token later 'returns the status and, once resolved, what actually changed.' It also covers rate limiting, cost, and appropriate content, making the tool's behavior completely specified for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant workflow context beyond the schema, especially for claim_token: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' It also maps feedback categories to usage scenarios, enhancing the enum semantics. It doesn't deeply enhance the 'context' object, but the schema already covers that.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates feedback types (bug, feature/data_gap, praise) and clearly distinguishes this tool from sibling tools like ask_pipeworx and discover_tools, which serve different purposes. The purpose is unambiguous and well-differentiated.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion boundary: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for non-Pipeworx tools, making the decision process 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, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable context: data source (CF analytics-engine), no PII, and caching policy (5min-1h). No contradictions.

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

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

The description is concise (two paragraphs) with bullet-pointed use cases. Every sentence adds value, and the structure is clear and front-loaded.

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

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

Given the tool's simplicity (one optional param, no output schema, rich annotations), the description covers all necessary aspects: purpose, return value, derivation, caching, and usage scenarios. It is complete for effective use.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume over a recent window' and lists three specific use cases. It distinguishes itself from sibling tools by focusing on aggregated trend data.

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

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

The description provides explicit use cases (e.g., discovering hot data sources, confirming canonical choice, seeing alignment). It doesn't mention when not to use or direct alternatives, but the context signals (sibling tool list) imply uniqueness.

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 true, and destructiveHint false. The description adds significant context: semantic anchor (Jaccard >=0.30), partition filter (placeholder fraction >20% returns null), fill check mechanism, and output structure. 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 lengthy but well-structured: general definition, mode specifics, semantic anchor, partition filter, response format, fill check, and reference to fill risk tool. Every sentence adds value, though conciseness could be improved slightly.

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

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

Despite no output schema, the description thoroughly explains the output structure (opportunities array, partition_check object), internal checks (Jaccard, placeholder filter, fill check), and even refers to polymarket_fill_risk for custom sizing. This fully covers the tool's behavior and usage.

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

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

Schema description coverage is 100% with both parameters documented. The description enriches each parameter: 'event' accepts slugs or full URLs; 'topic' explains cross-event search behavior and seed question usage. This adds value beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, differentiating it from siblings like polymarket_edges and 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?

The description explicitly recommends when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains the purpose of each mode but does not explicitly state when not to use it or compare to siblings.

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

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

Provides extensive behavioral context beyond annotations: caching behavior (1h KV cache keyed on all knobs), model family details, diagnostics, and edge computation nuances. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint all consistent).

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

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

The description is very long and dense, containing multiple paragraphs of technical detail. While well-structured with headings and clear organization, it is not concise. Every sentence carries useful information, but overall length reduces readability for quick scanning.

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

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

For a complex tool with 9 parameters, multiple response segments, and no output schema, the description is remarkably complete. It explains return structure (by_segment, diagnostics), edge computation, caching, and how to interpret results. No gaps identified.

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 9 parameters are described in the input schema (100% coverage), so the baseline is 3. The description adds significant value by explaining the interplay between parameters (e.g., min_partition_leg_kelly only applies to per-leg Kelly, slippage_pp context about Polymarket fees) and providing practical usage examples.

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 for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by being the primary edge discovery tool.

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

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

Explicitly states it is built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. Provides guidance on when to use through tradeable-edge knobs and model descriptions, though it does not explicitly mention when not to use or alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context: it uses daily snapshots, has a 60-day TTL, decay from daily closes, and explains response structure. It 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?

The description is thorough and well-structured, covering purpose, args, response, and limits. It is slightly verbose but each section adds value.

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

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

Despite no output schema, the description fully explains the response structure and limitations, making it complete for a telemetry 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 covers both parameters with descriptions (100% coverage). Description adds default values and valid options for 'window', enhancing parameter semantics.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question. It distinguishes from sibling tools by focusing on historical tracking rather than current edges.

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

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

The description implies usage for historical edge analysis but does not explicitly contrast with alternatives like 'polymarket_edges' or state when not to use.

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

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

Annotations already declare readOnlyHint=true (safe), idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond annotations: it details the internal walking of the order-book ladder, the verdict system (clean|degraded|cannot_fill), and for basket mode, the risk of forced_directional_risk. This provides transparency about what the tool computes and its limitations.

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

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

The description is long but well-structured: a clear opening sentence, separated single-market and basket sections using uppercase headers, and a conclusion with usage guidance. Every sentence adds value; there is no fluff. However, it could be slightly more concise by breaking into bullet points for readability, given the density.

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

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

The tool has no output schema, but the description comprehensively lists all return fields for both modes, including advanced concepts like capture_ratio, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also warns about the dominant loss mode in arb-bot P&L. Given the tool's complexity and the absence of output schema, the description provides a complete mental model.

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 meaning by explaining how parameters behave differently in single-market vs basket modes (e.g., size_usd interpreted as 'max spend on buys, target proceeds on sells' vs 'settlement notional shares per leg'), default values, and the auto-detection of side in basket mode. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly lists what it returns (top_of_book, vwap_fill_price, slippage_pp, etc.). This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional positions), providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond the annotations (which already indicate read-only, idempotent, open-world). It explains the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions that make spreads invalid (mismatched bet shapes, temporal mismatch). No contradiction with annotations.

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

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

The description is front-loaded with the purpose and well-structured with sections like 'TWO MODES' and 'SAFETY FIELDS'. It contains no fluff, but is somewhat lengthy. Every sentence adds value, but a slight reduction (e.g., combining some safety field explanations) 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 absence of an output schema, the description thoroughly explains the response format and edge cases (compatibility_warning conditions, temporal_alignment). It covers parameter combinations, expected behavior, and caveats, making it fully complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the two modes (topic vs explicit), listing the topic shortcut values, and noting that explicit tickers override topic-mapped sides. This goes well beyond the schema 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit tickers) and distinguishes itself from potential sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use each mode (topic vs explicit) and warns that most pre-mapped topics currently return compatibility warnings, meaning pre-mapped does not imply tradeable. It also explains safety fields (compatibility_warning, temporal_alignment) that help users assess when spreads are meaningful. However, it lacks an explicit 'when NOT to use' statement, though the safety information effectively covers that.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds scoping to identifier and pairing with other tools. However, it does not elaborate on return formats or error behavior, so it adds moderate value beyond annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then usage context, then scoping. Every sentence adds value and there is no redundant or extraneous text.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, pairing with siblings, scoping, and examples. It is fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with the single 'key' parameter described. The description echoes the schema's explanation (omit to list all keys) and adds context about using it for stored values, but does not provide additional semantic detail beyond what the schema already offers.

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

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

The description clearly identifies the tool as retrieving a value saved via 'remember' or listing all keys when omitted. It explicitly distinguishes from sibling tools 'remember' and 'forget' by describing the pairing.

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

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

The description provides explicit use cases (look up stored context) and implies alternatives by mentioning 'remember' and 'forget'. It lacks explicit when-not-to-use guidance but is clear enough for an AI agent to select correctly.

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

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

Annotations already indicate safety (readOnly, idempotent, not destructive). The description adds important context: the side effect of mark_read, the structure of returned events (source, citation_uri, payload), and polling behavior. No contradiction with annotations.

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

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

The description is well-structured: purpose first, then output details, then parameter guidance, then a note on polling. Every sentence adds value; no redundancy. Could be slightly more concise but still effective.

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

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

Given the lack of output schema, the description adequately covers what the tool returns and how to use parameters. It also mentions an alternative endpoint, providing a complete picture for an agent. However, it does not detail error handling or rate limits.

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

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

With 100% schema coverage, the description adds value by providing concrete examples (e.g., 'sec_8k' for type) and explaining the interaction between mark_read and subsequent calls. It clarifies usage 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 starts with a clear verb-resource pair ('Pull fired events from your subscription feed') and specifies the output contents. It distinguishes this tool from siblings like list_subscriptions, subscribe, etc., by focusing on retrieval of alerts.

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

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

The description gives clear filtering instructions (type, since) and a usage hint for mark_read. It also provides an alternative endpoint for scripts/dashboards, but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: fan-out to multiple sources, GDELT preferred with GNews fallback on rate limits, USPTO soft-fail due to API sunset, and return format with grouped changes and citation URIs. No contradiction with annotations.

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

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

The description is well-structured with examples, then behavioral details, parameter notes, return format, and sibling differentiation. It is informative but slightly verbose; however, every sentence adds value for a complex tool.

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

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

Given the multiple data sources, fallback mechanisms, and lack of output schema, the description is exceptionally complete. It explains the return format, the soft-fail for USPTO, and the alternative tool entity_profile for static data.

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

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

Schema covers all 3 parameters. The description adds significant meaning: `since` examples with ISO date and relative shorthand, suggestion for typical monitoring, `value` accepts ticker or CIK, `type` currently only supports 'company'. This provides actionable guidance beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing example queries and distinguishing from entity_profile. It explicitly details the data sources (SEC EDGAR, GDELT/GNews, USPTO) and the parallel fan-out behavior.

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

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

The description includes explicit usage examples and directs users to use entity_profile for static profiles. It explains the fallback between GDELT and GNews, and provides guidance on the `since` parameter with typical values ("30d" or "1m").

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

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

Discloses persistence behavior (authenticated vs. anonymous users) beyond annotations. No contradiction with annotations (readOnlyHint false, idempotentHint true, destructiveHint false). Could mention that updates overwrite existing key.

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

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

Four sentences, well-structured with front-loaded purpose. No redundant information, every sentence adds value.

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

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

Adequate for a simple key-value store with two required parameters. No output schema, but the return value (likely success) is implicit. Could mention error cases like duplicate keys or size limits.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds contextual examples for key patterns and value types, enhancing semantic meaning beyond schema.

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

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

The description specifies the verb 'save' and resource 'data to reuse later', with concrete examples (resolved ticker, user preference). It distinguishes from siblings 'recall' and 'forget', providing clear 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?

Explicitly states when to use ('when you discover something worth carrying forward'), includes pairing guidance ('pair with recall to retrieve later, forget to delete'), and notes scoping by identifier.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial context: multiple internal cascading lookups, graceful degradation of LEI/FIGI when upstream services are unavailable, source labelling, and explicit `unresolved` field rather than omission. This goes well 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 lengthy but efficient, front-loaded with the most useful example phrases and the core directive 'Use FIRST...'. Each sentence adds value—describing supported types, output sources, and fallback behavior. It is slightly verbose but well-structured, avoiding redundancy.

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

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

With no output schema, the description carries the burden of explaining results. It covers expected outputs for both company (CIK, ticker, LEI, FIGI, source labels) and drug (RxCUI, ingredient, brand, citation), plus the unresolved field and graceful degradation. It does not provide a full JSON example, but for a 2-param tool this is reasonably complete.

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

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

The schema already covers both parameters with good descriptions. The description adds significant meaning: it gives concrete accepted inputs ('ticker (AAPL), CIK (0000320193), or name'), explains the cross-source enrichment behavior, and clarifies how each type maps to outputs. While more detail could be added on output structure, it sufficiently enhances the bare 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 official identifiers, with specific verbs ('resolve a user-spoken NAME to the canonical/official identifiers') and concrete examples ('ticker for...', 'CIK for...'). It also differentiates from siblings like compare_entities and entity_profile by emphasizing it produces IDs for other tools.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use the tool or name alternative tools, so it lacks full differentiation against every sibling.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. 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?

Four sentences, front-loaded with the core purpose, then details. Every sentence adds value without unnecessary words.

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

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

Given 4 parameters and no output schema, the description covers the output (ranked list with score, confidence, signal density) and the operational logic (probes each entity, ranks). Slightly lacking in exact format, but sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting the first entity is treated as subject, which aids understanding 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?

The description states it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 usefulness for competitive AI-marketing audits with an example question. Does not explicitly state when not to use, but the context is clear and alternatives are implied via sibling list.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds details about graceful degradation, bundlephobia's first-measurement delay (5-30s), and the 'sources_failed' field. No contradiction.

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

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

The description is front-loaded with the core purpose. It contains three sentences, each with distinct information. Minor redundancy could be trimmed, but overall concise and well-structured.

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

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

Despite no output schema, the description lists all return fields (summary block, advisory details, links, alternatives) and explains partial failure. For a 2-param tool, this 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 value by explaining scoped package syntax for 'package' and the default behavior of 'version' (latest). This goes beyond schema descriptions.

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

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

The description clearly states the tool performs a composite check across deps.dev and bundlephobia for npm packages, answering questions about safety, popularity, and size. It distinguishes itself from siblings like 'scan_competitor_ai_presence' and mentions ecosystem scope.

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

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

Explicitly says when to use ('is X safe / popular / small') and provides exclusion guidance for non-npm ecosystems, directing users to 'deps.dev:version' for other package managers.

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

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

Description adds beyond annotations: explains that passages carry offsets for verification, technical details on embeddings (BGE-base-en, cosine, 500-char windows), and 200K char cap with truncation. 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?

Three dense sentences with no clutter. Front-loaded with purpose and key benefit, following with technical specifics. Every sentence earns its place.

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

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

Despite no output schema, description covers return values (passages with offsets and similarity scores), edge case (truncation), and pairing guidance. Complete for a 3-param 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%, so baseline 3. Description adds value with examples for query, defaults for limit, and explanation of embedding model and window size. Slightly 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?

Description specifies 'semantic search INSIDE a fetched record' with clear verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and context-saving benefit.

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

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

Explicit when-to-use: 'Use when the record is too big to cram into the prompt.' Provides alternative: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 context beyond annotations: it mentions idempotency (implicitly via 'idempotentHint: true' but not stated), authentication requirements, rate limits (10/day SMS), and webhook failure behavior. Annotations already indicate non-readOnly and non-destructive, and the description complements them without contradiction.

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

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

The description is front-loaded with the main action and packs substantial detail into a few sentences. It is well-structured but could benefit from bullet points for clarity. However, it remains efficient and avoids redundancy.

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

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

Despite no output schema, the description states the return value (subscription ID). It covers prerequisites, all subscription types, delivery channels, and constraints. Given the tool's complexity (3 parameters, nested objects), the description is thorough and leaves no critical gaps.

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

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

Schema coverage is 100%, and the description significantly enriches each parameter with type-specific examples (e.g., sec_8k items codes, delivery webhook signing details). It provides real-world usage patterns that go beyond the schema's description.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It uses specific verbs and resources, and distinguishes from sibling tools 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 prerequisites (Pipeworx OAuth account), supported subscription types with concrete examples, and delivery channel constraints (e.g., SMS cap, webhook auto-disable). It does not explicitly mention when not to use or compare to alternatives, but provides sufficient context for correct invocation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. Description adds that it returns live example questions with exact tool+argument shapes, and explains full spread vs. topic focus. 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?

Front-loaded with common queries, then explains use case, output, parameter, and usage sequence. 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?

No output schema, but description explains output format (category-bucketed examples with tool+argument shapes). Covers single parameter adequately. Annotations cover safety profile.

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?

Single parameter 'topic' has schema coverage 100%, but description adds meaning by listing possible values and explaining behavior when omitted ('cross-category spread').

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, specifying verb ('returns') and resource. It distinguishes itself from siblings by naming meta-tools like ask_pipeworx and positioning itself as the 'first' use.

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

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

Explicitly says when to use ('Use this FIRST when you do not yet know what Pipeworx can do') and how to focus via optional topic. No explicit when-not-to-use, but 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, idempotentHint=true, etc. The description adds 'current block height' and 'chain tip' context, which is useful but minimal. No behavioral traits beyond what annotations provide are disclosed.

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, front-loaded sentence with no unnecessary words. It is concise and to the point.

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

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

Given the tool's simplicity, the description is adequate. Output schema exists to describe return values, and annotations cover behavioral traits. The description explains what it does without needing further context.

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

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

Schema coverage is 100% for the single parameter 'network', with description in schema. The tool description does not add any additional semantic meaning 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 it returns the current block height of the chain tip. It is a specific verb+resource. However, it does not explicitly differentiate from sibling tools like 'block', which might also provide height, but the distinction is implied by the name and context.

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 the tool is for retrieving the current tip height, but provides no guidance on when to use it versus alternatives (e.g., 'block'). No exclusions or when-not-to-use scenarios are mentioned.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the behavioral profile is clear. The description adds no additional context like error handling, rate limits, or what happens with invalid txids. With annotations covering safety, a 3 is appropriate.

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, front-loaded sentence that efficiently conveys the purpose. However, it could be slightly more informative 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?

For a low-complexity tool with an output schema, the description provides minimal but adequate context. It lacks details about the optional 'network' parameter and behavior for invalid inputs, leaving some 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 description coverage is 0%, so the description must compensate. It only mentions the 'txid' parameter implicitly, but fails to explain the 'network' parameter or any parameter constraints. It does not add meaning beyond the parameter names.

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 'Transaction details by txid' clearly states the verb (retrieve) and resource (transaction details) with the key identifier (txid). It distinguishes from siblings like 'tx_status' and 'block' by focusing on details, but does not explicitly differentiate.

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 siblings such as 'tx_status' or 'block'. No exclusions, prerequisites, or context for choosing this tool are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it returns specific fields but does not explain what happens on invalid txid or the role of the 'network' parameter.

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

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

Single, front-loaded sentence with no wasted words. Efficiently conveys the core purpose.

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

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

Given the presence of an output schema and annotations covering safety, the description is mostly complete for a simple lookup tool. However, it could mention the optional 'network' parameter and error conditions for a truly complete picture.

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%. The description mentions txid and the return fields, but the 'network' parameter is not explained. The description adds some meaning beyond the schema but does not fully compensate for the missing parameter descriptions.

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

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

The description clearly states that the tool returns confirmation status (block_height, block_hash, confirmed) for a given txid, distinguishing it from sibling tools like 'transaction' which would provide full transaction details.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., 'transaction' for full details, 'mempool' for unconfirmed). The usage is implied but not clarified.

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 (destructiveHint false, idempotentHint true), the description reveals critical behavioral details: ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This adds significant 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 concise sentences with no redundancy. Key information is front-loaded: action, resource, ownership, and behavioral nuance. Every sentence serves a purpose.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description covers all essential aspects: what it does, constraints, side effects, and data preservation. 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% (parameter 'id' explained as 'Subscription id (uuid) returned by subscribe'). The description only restates 'by id', adding minimal new meaning. Baseline for high coverage is 3.

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

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

The description clearly states the action 'Cancel a subscription by id', specifying the resource (subscription) and scope (by id). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive nature (deactivation, not deletion). It implies use cases but does not explicitly list when not to use or compare to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds crucial behavioral context: it returns a structured verdict (confirmed, refuted, etc.), actual value with citation, and reasoning; it explains the distinction between could_not_verify (a failed check, not evidence) and unsupported (no source exists); and it discloses potential LLM/source failure with verification_error. This goes well beyond the annotations and helps the caller avoid misinterpreting results.

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

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

The description is long but front-loaded with query examples and purpose, then proceeds through routing, return values, and critical caveats. Every sentence is informative, though some parts (e.g., 'Replaces 4–6 sequential calls') are optional context. It is well-structured and not redundant, but 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?

There is no output schema, so the description carries the full burden of explaining what the tool returns—it enumerates the verdict values, the actual value with citation, and reasoning. It also covers error semantics and the two routing paths, giving the caller a complete mental model. For a tool of this complexity (two params, one required), this is very 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?

The schema covers 100% of parameters with detailed descriptions: claim has examples, tolerance_pct has range and override behavior. The tool description itself does not add extra parameter-level meaning beyond what the schema provides, so the baseline 3 applies. No gaps to compensate for.

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

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

The description opens with concrete natural-language examples ('Is it true that…', 'fact check') and states the tool performs 'claim verification against authoritative sources.' It clearly distinguishes itself from siblings by describing the SEC EDGAR fast path for company-financial claims and the grounded fallback for all other facts, and notes it replaces 4–6 sequential calls. This is a specific verb+resource with clear scope and 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. It also explains the internal routing logic (financial vs. other claims). However, it does not explicitly name an alternative tool for non-claim queries or state a when-not, so it stops short of the full explicit alternatives guidance.

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