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, so the safety profile is covered. The description adds valuable routing behavior (selecting from thousands of tools, filling arguments) and the citation URI return behavior. No contradiction exists.

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

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

The description is long but front-loaded and dense; the core directive appears first, followed by domain lists, trigger phrases, examples, and escalation guidance. Minor redundancy exists around the comparison to web search, but every section 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?

Although there is no output schema, the description states that the tool returns 'the structured answer with stable pipeworx:// citation URIs.' It covers when to use it, what kinds of questions to send, concrete examples, and when to step up to deep_research, making it complete for a router-style tool.

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

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

Schema description coverage is 100% and the schema already documents the 'question' field and aliases. The description adds value by giving concrete natural-language examples like 'current US unemployment rate', 'Apple's latest 10-K', and 'adverse events for ozempic', which help the agent craft an appropriate question 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 opens with 'PREFER OVER WEB SEARCH' and states clearly that the tool 'routes the question to the right one of 5,767 tools across 1506 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is a specific verb-plus-resource definition that also distinguishes it from web search and deep_research.

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

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

The description gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and states it should be used 'even if web search could also answer it.' It also names an alternative for broader multi-part questions: 'use deep_research'.

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

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

Annotations already declare the tool read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context beyond that: candidate routing improvements are live when under test, no candidate is currently active, and the tool does not fall back to a stub but is a fully working router. This gives agents an accurate picture of the experimental and changing behavior without contradicting any annotation.

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 identity of the tool, then adds current state, usage direction, and a clarifying statement that it does not fall back to nothing. It is somewhat dense, and the specific retirement date is arguably extra detail, but every sentence contributes necessary context for an experimental tool variant. Overall it is well structured without being wasteful.

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

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

For a live experimental router with no output schema, the description covers the current behavior, the relationship to the stable version, and the fact that the response shape is identical to ask_pipeworx. It does not independently spell out the response format, instead deferring to ask_pipeworx's shape, which is an acceptable but slightly incomplete solution. All invocation semantics are otherwise covered.

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?

Parameter coverage in the schema is 100%, with all six parameters documented, including the primary 'question' field and the aliases q, text, input, query, and prompt. The description only says 'same arguments' as ask_pipeworx, which adds no meaningful semantic detail beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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

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

The description identifies the tool as a beta version of ask_pipeworx and explains it is an identical universal router over 5,767 tools with the same arguments and response shape. It clearly distinguishes the tool from the stable ask_pipeworx sibling by the key difference: candidate routing improvements enabled live. This is specific enough for an agent to know exactly what the tool does and how it relates to its siblings.

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

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

The description gives an explicit usage instruction: 'Use it exactly like ask_pipeworx when you want the newest routing,' and it explains that results are compared against the stable router to inform merges. This gives a clear condition for selecting this tool over the stable version. It does not explicitly mention when not to use it or compare against ask_pipeworx_grounded, so it is strong but not exhaustive.

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

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

The description adds substantial behavioral transparency beyond the annotations: it reveals that the tool will either return a structured answer with verbatim evidence and confidence, or explicitly refuse with a refusal_reason enumeration. It also discloses that it only uses the tool result and cannot invent facts. There is no contradiction with the readOnlyHint, openWorldHint, or idempotentHint 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 every sentence contributes: purpose, behavior, return shape on success, refusal behavior, use cases, and cost tradeoff. The core distinguishing trait (grounded extraction) is front-loaded, and the alternative (ask_pipeworx) is mentioned with a concrete selection criterion. There is no filler or repeated schema content.

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

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

This is a complex routing tool with no output schema, so the description correctly takes on the burden of specifying return values. It fully describes both the success return object and the explicit refusal object with all refusal reasons. It also covers when to use versus avoid it and the operational cost, making the description complete for an agent deciding whether and how to invoke it.

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

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

The input schema already documents the question parameter and all five aliases (query, q, prompt, text, input) with 100% coverage. The description does not add parameter-level detail, which is acceptable because the schema fully carries that burden. The description's reference to routing and argument filling is contextual rather than parameter-specific, 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 clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads. It names the specific behavior (extracting the answer using ONLY what the tool result contains) and distinguishes itself from the sibling ask_pipeworx by stating it is 'Same routing as ask_pipeworx' but with grounded extraction. An agent can easily tell when this tool is the intended choice.

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 is explicit: use this tool when an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains given (financial verdicts, legal claims, medical lookups, public statements). It also explicitly says to prefer ask_pipeworx for casual lookups because this costs one extra LLM call. This is strong 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 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 indicate safety, and the description adds substantial behavioral context: parallel decomposition across 5,767 tools, a findings packet with verbatim evidence + confidence + source + citation URI, explicit gaps[] for unanswered facets, contradictions[], hop fields, semantic excerpting, and latency expectations. This far exceeds what the annotations alone provide and contains 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 long, but each sentence adds required operational knowledge: auth, alternatives, tool behavior, output format, timing, and limitations. It is front-loaded with the most critical gate (account required). A slight tightening would improve it, but nothing is redundant.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet contents, confidence, sources, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and fetchable citation_uri. Combined with auth, pricing, latency, and alternative routing, an agent has everything needed to call this 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%, so the baseline is 3, and the description adds genuine extra semantics: it ties the depth enum to cost ('thorough' needs a paid plan), explains the behavioral difference between 'standard' and 'thorough' hops, and clarifies that the question parameter supports broad/multi-part input. This is more than the schema provides, though not overwhelming.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in ONE call, and explicitly contrasts itself with 'open-web search.' This clearly distinguishes deep_research from sibling tools like ask_pipeworx and search_within.

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. It also names the alternative ask_pipeworx for single lookups, breaking news, and when not signed in, plus notes the paid plan requirement for 'thorough' depth. This is model-level routing clarity.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the tool's internal fan-out across many data sources, the soft-fail behavior for the USPTO API, the semantics of empty sections, and the resolved_from/resolved_to behavior. It also explains the type parameter's interchangeability, which is real behavioral context. No contradiction with annotations.

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

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

The description is long and dense, but nearly every sentence carries operational value: examples, source enumeration, return fields, failure semantics, and input resolution rules. It is front-loaded with the core purpose and ALWAYS-PREFER directive, though the single run-on opening sentence could be split for better readability.

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

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

Despite having no output schema, the description specifies the full return shape: fields like cik, company_name, resolved flags, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers edge cases like empty sections and private companies, making it effectively complete for an agent to call and interpret results.

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

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

Schema coverage is 100%, but the description still adds substantial meaning: it explains that names resolve via SEC EDGAR, that CIK values should be zero-padded, that tickers can be passed even when type is 'company', and that private companies produce resolved:false with notes. This goes well beyond the schema's terse field 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 opens with concrete user-phrase examples and immediately identifies the tool's function: producing a full cross-source profile of a US public company in one parallel call. It clearly distinguishes this from chaining single-pack lookups and from siblings like deep_research or resolve_entity by positioning it as the holistic-company-view 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?

It explicitly says to prefer this over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, and details when a name resolves versus when it doesn't. It also explains expected behavior for private companies and for companies with no FDA biologics, so an agent knows when the tool succeeded versus when it legitimately returned nothing.

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 goes far beyond the annotations by disclosing critical behaviors: compatibility_codes can be non-empty even when matched_pairs>0, temporal_alignment null means unknown rather than aligned, unknown legs are never paired, pairing_unverified is always set, and all spreads are gross of Kalshi fees. This adds substantial operational context beyond the readOnly/idempotent hints.

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 it is well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core definition before safety details. It is dense rather than padded, though some safety explanations are repeated. Each sentence earns its place given the complexity.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, skipped counts, compatibility codes, fee disclosures, and null semantics. Nothing critical appears missing for an agent to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that both modes run the same token-overlap matcher, that explicit tickers override the topic-mapped side, and how the safety fields behave in either mode. This adds genuine value, though not enough to reach 5 given the schema already documents the parameters.

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

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

The description clearly states the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It names the resource and operation precisely and explains the two modes (topic and explicit). However, it does not explicitly distinguish this tool from sibling tools like polymarket_arbitrage, so it stops short of full sibling 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 gives strong usage context: when to use topic shortcuts versus explicit event tickers, that both modes use the identical matcher, and that pre-mapped topics often return compatibility warnings. It does not explicitly state when not to use this tool or name alternative sibling tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=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?

Beyond the read-only, idempotent, open-world annotations, the description reveals important behaviors: graceful degradation if GLEIF/OpenFIGI is unavailable, returning figi_candidates when ambiguity arises, marking unresolved identifiers explicitly, and labelling every identifier with its source. This gives an agent an accurate mental model of the tool's 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 and information-dense, but it is front-loaded with the purpose and 'USE FIRST' directive, and each paragraph covers a different aspect (supported types, behavior, parameter semantics). Some redundancy exists (e.g., repeating identifier types), so it isn't perfectly concise, but nothing is filler.

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

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

With no output schema, the description carries the burden of explaining return behavior: it explicitly mentions figi_candidates, unresolved fields, source labels, and fallback behavior when enrichment services are unavailable. Combined with the detailed parameter guidance, an agent has everything needed to call and interpret the tool.

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

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

Even though the input schema already documents both parameters, the description adds crucial semantics: 'Pass the ENTITY NAME ONLY', example values (AAPL, 0000320193), and a concrete warning that trailing security-class words will make a bond lookup fail. This goes well beyond the schema's coverage, which is 100%.

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

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

The description opens with concrete example queries and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the exact action (resolve), the resource (names to identifiers), and enumerates supported types (company, drug), clearly differentiating it from sibling tools like entity_profile or compare_entities.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID' and explains that it replaces 2-3 manual lookups. It doesn't explicitly name alternatives for when-not-to-use, but the 'use FIRST' directive is strong and the supported-type breakdown clarifies scope.

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.