Alchemy Eth

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds critical behavioral context: invoking Anthropic requires a user-provided _apiKey and incurs direct cost ('BYO key — you pay Anthropic directly'). It also clarifies that the default Workers AI model is free, which is not apparent from 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, each with a distinct purpose: the action and output, the model selection and cost behavior, and the use cases. It is front-loaded with the core function and contains no redundant filler relative to the schema.

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?

Since there is no output schema, the description compensates by explicitly listing the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers model selection, key handling, and use cases, making it fully sufficient for an AI agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100% with good descriptions for all parameters. The description goes further by explaining the default model ('Workers AI Llama-3.3-70b'), the relationship between _apiKey and models ('pass _apiKey to also probe Anthropic'), and how omitting 'models' defaults to workers-ai.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the output ('score visibility (0-100) per model'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on multi-LLM visibility scoring with a numerical output.

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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use it. However, it does not name alternative tools or exclusions, such as noting that 'scan_competitor_ai_presence' might be more suitable for competitor-focused scans.

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. The description adds behavioral context: it routes to multiple internal tools, fills arguments automatically, returns pipeworx:// citation URIs, works on every tier, and is described as a fast default entry point. This goes beyond the annotations without contradicting them.

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

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

The description is long but information-dense, with clear sections for positioning, usage triggers, examples, and alternatives. Each section serves a purpose in helping an agent decide when to use this tool. It could be trimmed slightly, but given the tool's role as default entry point, the length is justified.

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

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

The description covers purpose, usage, alternatives, return format (citation URIs), performance characteristics, and scope examples. Given the absence of an output schema, the return format mention is sufficient. No gaps are apparent.

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 aliases, and the description adds useful examples of natural language questions across domains. It also notes the tool 'fills arguments', implying the single question parameter is sufficient. This provides meaningful context beyond the schema's generic alias 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 routes questions to 5,501 tools across 1441 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

It explicitly instructs to prefer this over web search for factual queries and lists trigger phrases ('what is', 'look up', 'find'). It also provides exclusions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses beta behavior: it may have live candidate routing enabled at times, currently matches ask_pipeworx exactly because no candidate is active, and it is a full working router with no fallback. This is valuable context about stateful behavior and safety that annotations do not convey.

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

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

The description is four sentences and front-loaded with the key fact that this is a beta variant. It is mostly efficient, though there is minor redundancy between stating 'same 5,501 tools, same arguments, same response shape' and later 'currently matches ask_pipeworx exactly.' Overall it earns its place but could be tightened slightly.

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

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

Given no output schema, the description still covers the response shape ('same response shape'), current runtime state (no active candidate), relationship to the stable router, and the experimental purpose. For a relatively simple universal-router tool, this is complete and actionable 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% and every parameter (question plus five aliases) is described clearly in the schema. The description only says 'same arguments' as ask_pipeworx, which adds no additional meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 identifies the tool as a beta variant of ask_pipeworx, describes it as an identical universal router with the same argument/response shape, and distinguishes it from the stable sibling ask_pipeworx and the grounded variant. It uses a specific verb ('ask' / router) and resource, leaving no ambiguity about what the tool does.

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

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

Explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the experimental context (candidate routing improvements compared against the stable router) and clarifies that it is a fully working router, not a fallback. This provides clear guidance 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?

Beyond annotations (read-only, open-world, idempotent, non-destructive), the description discloses the grounding constraint (uses only tool result), the explicit refusal reasons, the return structure (success vs refusal), and the extra LLM call cost. This is substantial behavioral context that goes far beyond the annotations.

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

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

The description is moderately long but front-loaded with the core purpose. Every sentence adds value: mechanism, return format, use case, and cost comparison. It is well-structured, though slightly verbose in the routing explanation.

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

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

The description covers success and refusal return structures, usage contexts, alternatives, cost, and behavioral guarantees. Given the tool's complexity and lack of an output schema, the description explicitly documents the return shapes, making it 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?

The schema has 100% coverage for all six parameters (aliases for 'question'), so the baseline is 3. The description does not add any additional parameter-level details; it only mentions 'fills arguments' generically. The schema already fully documents the 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 states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and explains its mechanism (extracts answer only from tool result). It distinguishes from the sibling ask_pipeworx by emphasizing the grounding and refusal behavior, making the tool's purpose unmistakable.

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

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

Explicitly provides both when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use ('prefer ask_pipeworx for casual lookups'). It also names the alternative (ask_pipeworx) and explains the cost tradeoff.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description aligns with these (fetch is read-only) and adds the use of Alchemy's RPC as a behavioral detail, but does not disclose additional traits like rate limits or error behavior. 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?

A single sentence front-loads the core action and method, then efficiently lists the parameters. Every clause contributes value, with no redundant statements 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 the tool's simplicity and the presence of an output schema, the description adequately covers the function. However, it does not clarify how the 'specified chain' is supplied or whether any parameters are required, which is a minor gap given the schema is empty.

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 no properties, so the description carries the full burden of parameter semantics. It explicitly enumerates seven passthrough parameters (fromBlock, toBlock, fromAddress, toAddress, contractAddresses, category, maxCount), providing meaning far beyond the empty 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 identifies the action ('Fetch'), resource ('Ethereum asset transfer history'), and specific RPC method ('alchemy_getAssetTransfers'), while specifying the chain context. This level of specificity distinguishes it from sibling tools like eth_call or token_balances without needing explicit contrast.

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 used for fetching asset transfers but provides no explicit guidance on when to choose it over alternatives, nor any exclusions or prerequisites. The passthrough parameter list hints at usage context but does not state 'use this when...'.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds extensive context beyond that: fan-out patterns, resolver contract with match confidence, parent event extractor, safety short-circuit for low-confidence matches, market_closed_or_inactive status, wide-spread tradeability notes, and cancellation rule risk with EV impact. It also discloses blocking behavior and the recurring pure-rules loss from flat-50¢ void settlements. 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 quite long (~700 words) but uses all-caps section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize content. It is front-loaded with the core purpose, but the extensive examples and edge-case explanations make it verbose. It is well-structured but not concise.

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

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

With no output schema, the description must explain return values and behavior comprehensively. It does so, covering response shapes for market/analysis/evidence, resolver contract fields, parent_event details, news fallback fields, safety statuses, closed-market handling, wide-spread warnings, and cancellation rule semantics. This is exceptionally complete for a complex tool.

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

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

Schema description coverage is 100% for all three parameters. The tool description restates the market parameter's accepted formats but does not add information beyond what's already in the schema. The depth and include_raw parameters are fully described in the schema and not expanded in the description. Thus the description provides no additional parametric value over the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by the one-call fan-out mechanism and category-specific data packs. It also lists explicit user intents like 'should I bet on X' and 'what does the data say about Y'.

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 context and use cases ('Use for "should I bet on X"...'), and even provides guidance on when to inspect resolver contract and cancellation risk. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full when/when-not/alternatives specification.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behaviors: it pulls from SEC EDGAR/XBRL for companies and FAERS/FDA/trials for drugs, handles off-calendar fiscal years correctly, sorts results by a primary metric, and returns paired data with citation URIs. This adds substantial context beyond the structured annotations.

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

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

The description is longer than average but every sentence delivers useful information: trigger phrases, count limits, data sources, fiscal-year handling, sorting, and output format. It is front-loaded with usage cues and structured logically. It earns its length given the tool's dual-type 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 adequately summarizes the return value (paired data + citation URIs, sorted by primary metric) and the data points per entity type. It does not provide a precise response shape or unit details, but for a read-only comparison tool with clear parameters, this is sufficient for an agent to understand and invoke it correctly.

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

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

The input schema already documents both parameters fully (type enum with descriptions, values array with min/max and examples). The description goes further by explaining what each type actually retrieves (latest 10-K financials vs. FAERS counts), thereby enriching the semantic meaning of the 'type' parameter beyond the schema's basic enum 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 identifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single call. It uses specific verbs like 'compare' and lists concrete example query patterns ('X vs Y', 'which is bigger'), and distinguishes itself from single-entity lookups by emphasizing it replaces 8–15 sequential calls.

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 this tool: whenever comparing entities, and it strongly prefers it over sequential single-pack lookups. It gives concrete trigger phrases and describes what each type pulls. However, it does not explicitly name an alternative tool (e.g., entity_profile) or say when not to use it, though the guidance is still 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?

As annotations already declare readOnly/openWorld/idempotent hints, the description adds substantial context: it won't invent answers (gaps[] are empty), citations are always fetchable via pipeworx:// URIs, large records are semantically excerpted, latency expectations are provided (15-90s), and depth levels are explained in terms of iterative hops and contradiction scanning. This goes far beyond the annotations and paints a complete picture 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?

Although lengthy, the description is densely packed with essential facts, front-loaded with the account requirement, and logically organized: purpose, mechanics, output, use cases, depth variants, and edge cases. Every sentence contributes unique guidance (e.g., what NOT to use it for, how citations behave, what 'thorough' adds). For a tool of this complexity, the length is justified 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?

The description covers what the tool does, its output format (findings packet with evidence, confidence, source, fetched_at, citations), limitations (gaps when topic isn't in structured catalog), alternatives, depth behavior, latency, and account requirements. Since there is no output schema, this description carries the full burden of explaining what the agent can expect, and it does so completely.

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%: both `question` and `depth` are fully described in the input schema, including the meaning of each depth value and the fact that broad/multi-part questions are acceptable. The description mostly restates the schema's depth semantics (gap recovery, iterative hops, contradictions) and adds payment/latency context, which is more about behavioral transparency than parameter meaning. It does not significantly augment the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb+resource+scope: it performs 'grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' in one call, explicitly distinguishing itself from open-web search and from siblings like ask_pipeworx. It directly cites the sibling for single lookups, making the differentiation clear.

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: best for 'broad/multi-part questions over structured data', for a single lookup use ask_pipeworx, and for breaking/current-news topics prefer ask_pipeworx because deep_research returns empty gaps. It also notes account prerequisites and when thorough depth is paid, giving clear when-to and when-not-to use instructions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: it returns top-N relevant tools with full schemas and curated examples, ready to call without a second schema lookup. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then provides a useful list of example data domains, and ends with return behavior and a tactical 'call first' directive. It's slightly long but every sentence contributes information; the domain list earns its place by clarifying coverage.

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

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

No output schema exists, so the description's explanation of return contents (top-N tools, names, descriptions, full input schemas with curated examples) is valuable. It covers what the tool does, when to use it, and what to expect from output, which is sufficient for a discovery tool of moderate complexity.

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

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

Schema coverage is 100%, with each parameter already described (including aliases for 'query'). The description mentions 'describing the data or task' which aligns with the query/task parameter, but adds no new syntax or format details beyond the schema. Baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a discovery tool from sibling tools, which are domain-specific, by stating it returns tool names, descriptions, and schemas.

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

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

It provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly tells the agent when to invoke this tool and sets it apart as an initial exploration step.

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 cover read-only and non-destructive behavior. The description goes further by disclosing that patents 'soft-fails until reactivated' due to an upstream API sunset, and that names are unsupported inputs. These are behavioral traits an agent needs.

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

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

The description is long but dense; every clause adds either usage examples, data source context, return structure, or a limitation. It could be tightened slightly but is well-structured.

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

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

For a read-only research tool with no output schema, the description thoroughly covers inputs, behavior, return fields, and known failure modes. It gives an agent everything needed to decide and invoke correctly.

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

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

Schema has 100% coverage; both parameters are fully described in the schema with examples and the name limitation. The description repeats this information but adds no new parameter-specific semantics beyond the schema, hence baseline 3.

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

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

The description opens with concrete query examples and clearly states it produces a 'full cross-source profile' via a single parallel call. It distinguishes itself from siblings by explicitly saying to prefer it over chained single-purpose lookups and lists exact return fields (CIK, filings, fundamentals, patents, news, LEI).

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a conditional: if only a name is given, use resolve_entity first. This is strong when-to-use guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds the default chain and Alchemy as the backend, but does not disclose additional behavioral traits such as rate limits, error handling, or response format. This is acceptable given the annotation coverage, but it does not exceed expectations.

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

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

The description is a single, well-structured sentence that front-loads the core purpose. It includes relevant examples and zero filler, making it concise and easy to scan.

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

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

The description is sufficient for a generic JSON-RPC passthrough tool. It covers the method, parameter passing, and chain default, and the presence of an output schema reduces the need to explain return values. It could mention supported chain values or note that params must be a JSON array, but the examples already imply this, so the gap is minor.

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 schema property descriptions absent (coverage 0%), the description compensates by explaining the 'method', 'params array', and 'chain' (including the default). Examples illustrate exact parameter usage (e.g., eth_getBalance with address and 'latest'). This adds meaningful context beyond the bare schema.

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

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

The description clearly states a specific verb ('Execute') and resource ('any Ethereum JSON-RPC method'), with examples that clarify the scope. It distinguishes itself from specialized siblings like token_balances or nft_metadata by framing this as a generic passthrough for arbitrary methods.

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

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

It provides clear context: use this tool to call any JSON-RPC method on a specified chain. However, it does not explicitly mention when to prefer specialized sibling tools instead, so the guidance is clear but lacks explicit exclusions or alternative recommendations.

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 flag destructiveHint, idempotentHint, and readOnlyHint. The description confirms deletion but adds little beyond the annotations. It mentions clearing sensitive data, which is a rationale, not a distinct behavioral trait. Since the annotations carry the main transparency, this is adequate but not enriched.

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

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

Three concise sentences: the first states the action, the second gives use cases, the third references related tools. No wasted words.

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

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

For a single-parameter delete tool with strong annotations and no output schema needed, the description covers purpose, usage, and context. It could mention return behavior but that's not critical given idempotency and simplicity.

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 fully describes the single `key` parameter with 100% coverage. The description adds no additional semantic details about key format or behavior; it only restates that deletion is by key.

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 'Delete a previously stored memory by key,' which precisely states the action and target. It clearly distinguishes this from sibling tools like remember and recall by indicating it's the delete operation.

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

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

It provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data...' It also references remember and recall as companion tools, though it doesn't explicitly state an alternative for retrieval, so slightly short of a 5.

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 behavior. The description adds valuable process details beyond those hints: it fetches the page, extracts title/description/key links, emits standard llms.txt markdown, and returns a text blob for site-root placement. This enriches the safety profile without contradicting it.

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 deliver the core action, process, output format, and use cases without wasted words. The first sentence leads with the primary purpose, and every sentence adds distinct information.

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

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

With no output schema, the description correctly explains that the result is a single text blob in standard llms.txt markdown. It covers the external fetch behavior and intended placement, which is sufficient for an agent to understand outcomes; exact error handling details are not necessary.

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

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

Schema description coverage is 100%, so the schema already documents url and max_links with clear meanings. The description adds only broad context ('key links', 'standard llms.txt format') and does not provide additional parameter-specific semantics, matching the baseline for high schema 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?

The description opens with a specific action and target: 'Generate a production-ready llms.txt file for any URL.' It clearly identifies the resource, the output, and the use cases, distinguishing it from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than visibility analysis.

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

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

The 'Useful for' list explicitly states when to use the tool: getting a client's site indexed, drafting llms.txt for a project, or auditing competitor pages. It does not provide when-not-to-use guidance or name alternatives, but the listed scenarios provide clear context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context by specifying the return fields and the scope ('caller's active subscriptions'), which helps the agent understand what to expect. 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 two sentences with no fluff. The first sentence states the action and return fields, the second provides practical usage context. Every word earns its place.

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

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

For a simple read-only list tool with one optional parameter, the description covers purpose, return fields, and usage. It lacks notes on pagination or ordering, but these are not critical given the tool's simplicity. The annotations and schema fill in the remaining context.

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

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

Schema description coverage is 100%, so the single parameter include_inactive is already fully documented. The description adds no extra parameter semantics beyond implying the default is active subscriptions, which is already in the schema. This meets the baseline for high schema 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?

The description clearly states the tool lists the caller's active subscriptions, naming a specific verb and resource. It also enumerates the return fields, which makes its functionality explicit. This differentiates it from sibling tools like subscribe/unsubscribe by positioning it as the read-only listing counterpart.

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 concrete usage guidance: use before adding more subscriptions (i.e., subscribe) and to find an id for cancellation (i.e., unsubscribe). This implies the appropriate context and alternatives, though it does not explicitly name the sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the annotations, such as caching behavior, chain handling, or response shape. It provides no extra value for an agent.

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

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

The description is extremely short, but for a tool with 4 parameters and a specific purpose, this is under-specification rather than deliberate conciseness. It omits critical information that would fit in a few more sentences.

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

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

With a 4-parameter schema, sibling tools, and an output schema, the one-line description is insufficient. It does not address chain defaults, the meaning of refresh_cache, or how this differs from nfts_for_collection. The output schema covers return values, but usage and selection context is missing.

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 has 0% description coverage, so the example is the only hint for parameters like contract and tokenId. The description does not explain any parameter semantics, nor does it clarify optional parameters like chain or refresh_cache. An agent cannot understand what inputs to provide beyond the example.

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 'Single NFT metadata' clearly identifies the tool's scope as metadata for one NFT, which distinguishes it from siblings like nfts_for_collection or nfts_owned. However, it lacks an explicit verb like 'retrieve' or 'get', so it's not a fully specified purpose statement.

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?

There is no guidance on when to use this tool versus alternatives such as nft_owners, nfts_for_collection, or nfts_owned. The description does not mention use cases or exclusions, leaving the agent to guess.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context such as pagination, response size limits, or what 'owners' means (e.g., does it include all owners or just current?). It provides zero value beyond the annotations.

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

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

The description is extremely short, but this is under-specification rather than effective conciseness. Every word is generic and does not add meaningful information. It does not front-load key details or structure the response in any helpful way.

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

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

The tool has an output schema, but the description does not mention what the output contains or how it is structured. It is also missing any context about tokenId vs. contract scope, chain support, or how it relates to sibling tools. This is completely inadequate for a tool that needs to be selected among many similar NFT-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 three parameters (chain, tokenId, contract) with zero description coverage. The description only hints that 'contract/token' are involved, which weakly maps to contract and tokenId, but it does not explain the role of chain, the requiredness of contract, or how tokenId filters results. It fails to compensate for the lack of 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 'Owners of a contract/token' is a noun phrase that restates the tool name without a specific verb or clear action. It gives some context that this relates to NFT ownership, but it does not distinguish from siblings like nfts_owned or nfts_for_collection, nor does it clarify whether it returns current owners, historical owners, or a count.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention that tokenId narrows to a specific token, nor any exclusions or prerequisites. The description is entirely silent on usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context beyond the annotations—no mention of pagination, limits, or query behavior. It contributes nothing extra.

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 only three words and lacks a sentence structure. This is under-specification rather than conciseness; it does not convey any actionable information in a structured way.

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 5 parameters and a defined output schema, this tool requires a clear explanation of its purpose and parameter roles. The description is a fragment that fails to provide any of this context, making it nearly impossible for an agent to use correctly.

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

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

Schema description coverage is 0%, and the description provides no explanation for any of the 5 parameters. Even the required 'contract' parameter is left unexplained. The description fails to compensate for the missing schema documentation.

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

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

The description 'NFTs in a collection' is a noun phrase that essentially restates the title 'Nfts For Collection'. It lacks a verb and fails to specify the operation (e.g., list, fetch, retrieve). It also does not distinguish this from sibling tools like 'nft_owners' or 'nft_metadata'.

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?

There is no guidance on when to use this tool versus alternatives. No mention of typical use cases, prerequisites, or scenarios where another tool would be more appropriate. The agent is left without context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, repeatable read operation. The description adds no further behavioral context such as pagination behavior, multi-chain support, or the meaning of openWorldHint. It is essentially a restatement of the title.

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 brief and avoids redundancy, but it is under-specified rather than productively concise. A single noun phrase conveys the core idea but lacks the structure of a full sentence like 'Gets the list of NFTs owned by a wallet address.'

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 5 parameters and an output schema, the description is starkly minimal. It gives no guidance on pagination, filtering, chain behavior, or when to use this tool. The output schema covers return values, but the contextual usage and parameter semantics are largely missing.

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 needed to explain parameters. It only hints that 'owner' is an address via the phrase 'by address,' but does not explain 'contracts', 'chain', 'page_key', or 'page_size'. The examples in the schema provide some clues, but the description itself does not compensate.

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 'NFTs owned by address' clearly identifies the resource (NFTs) and scope (by wallet address), distinguishing it from siblings like nft_owners (reverse lookup) and nfts_for_collection. However, it lacks an explicit verb such as 'Gets', so it is not a fully specified 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 provides no guidance on when to use this tool versus alternatives. It does not mention that this tool is for looking up NFTs held by a wallet, nor does it reference related tools like nft_owners or nfts_for_collection. No exclusions or alternative use cases are indicated.

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 are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the burden. It discloses rate limiting, the claim_token mechanism, and that it's free and doesn't count against quota. It adds meaningful behavioral context beyond structured annotations, though it doesn't detail data retention or synchronicity.

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 each sentence adds value: purpose, usage, exclusions, token explanation, rate limits, and quota note. It is structured logically and front-loaded with the core purpose. Slightly verbose but not wastefully so.

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

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

The description is complete for this tool's complexity. It covers the full lifecycle: filing feedback, receiving a claim_token, and later reading the resolution. It also clarifies the one edge case (wrong MCP server) and sets expectations about daily rate limits and quota. No output schema exists, but the description covers the return token adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic guidance on how to use the message parameter (describe issues in terms of Pipeworx tools, don't paste end-user's prompt) and explains the claim_token parameter's behavior (passing it back to read status). 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 explicitly states the tool's purpose: to tell the Pipeworx team about broken, missing, or needed tools. It uses a specific verb-resource pairing ('Send Pipeworx Feedback') and clearly distinguishes this from sibling tools (e.g., ask_pipeworx) by limiting scope to feedback about Pipeworx 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 gives explicit when-to-use guidance: for bugs, feature requests, data gaps, or praise. It also provides exclusions (e.g., feedback must be about Pipeworx-served tools, not other MCP servers) and directs users to the correct alternative when applicable. This is comprehensive usage 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond this: it states the data is 'derived from CF analytics-engine, no PII,' and that results are 'Cached 5min-1h depending on window.' These details tell the agent about freshness, source, and privacy, which annotations do not cover.

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

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

The description is three sentences, front-loaded with the core purpose, followed by use cases, then technical context. No fluff; each sentence earns its place. The use-case list is slightly numbered but remains compact.

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

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

Even without an output schema, the description states what is returned ('top tools, top packs, and total call volume') and the data shape ('(pack, tool, count)'). Combined with the simple parameter schema and strong annotations, the description fully equips the agent to use the tool correctly.

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

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

The schema description already explains the window parameter's trade-off (shorter vs longer windows), and the tool description reinforces it. The additional value comes from linking caching behavior to the window ('Cached 5min-1h depending on window'), which adds a behavioral nuance not present in the schema. However, this is marginal, so a score of 4 is appropriate.

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

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

The description clearly identifies the tool as a trend aggregator for Pipeworx calls, stating it 'Returns the top tools, top packs, and total call volume.' It distinguishes itself from sibling tools like discover_tools by focusing on what agents are currently using rather than query-based discovery. The verb 'Returns' plus the specific resource makes it unambiguous.

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

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

The 'Useful for' section lists three concrete scenarios (discovering hot data sources, confirming canonical tools, aligning use case with agent demand). It does not explicitly state when not to use it or name alternatives, so it falls short of full exclusion guidance, but the use cases provide strong context for when this tool is appropriate.

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

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

Despite annotations already declaring read-only and idempotent hints, the description adds rich behavioral detail: threshold deviations (>3pp emit a signal), similarity filtering (≥0.30 Jaccard), placeholder fraction limit (>20% returns null), and the fill check behavior (realizable_edge_pp ≤ 0 means don't trade). It also explains the response structure. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Each sentence carries meaningful information. It is appropriately detailed for a complex tool, though slightly verbose; still, 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?

With no output schema, the description must explain return values, and it does: 'opportunities[] (gap_pp, suggested_trade, reasoning...)' plus the partition_check object. It also covers edge cases, fill-check behavior, and alternative tools, making it complete for an agent to invoke correctly.

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

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

The input schema already describes both parameters, but the description goes far beyond by giving concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explaining how each mode processes the input (event walks child markets and runs partition_check; topic flattens related events). It adds semantics not present in the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage and specific methods. It also explains the three invocation modes (trending_scan, event, topic), removing ambiguity.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets and topic mode for cross-event scanning, and even names an alternative tool: 'For custom sizing use polymarket_fill_risk.' It also explains when cross-event mode is advantageous.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral traits: three model families with specific formulas, placeholder-slug filtering, partition skipping rules, rare-by-design longshots, slippage assumptions, 24h-move warnings, and 1h caching at the KV level. This far exceeds what annotations provide.

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

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

The description is very long but front-loaded with the core purpose and user intent. It is dense with valuable technical details that aid correct invocation. While every sentence adds information, the length could be trimmed; however, given the tool's complexity, the structure is acceptable and not 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?

Even though there is no output schema, the description thoroughly explains the response structure: by_segment grouping, fed_candidates, and _diagnostics with funnel counters. It covers all major behavioral aspects, knobs, and edge cases, making it complete enough for an agent to select 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%, so the baseline is 3. The description adds meaningful context on how parameters interact, e.g., 'min_partition_leg_kelly filters partitions by best per-leg Kelly' and 'min_kelly never filters partition arbs because basket trades don't compose to single-leg Kelly.' This extra semantic enrichment justifies a 4.

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

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

The description states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also names the intended use case ('what should I bet on today') and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on discovering opportunities rather than executing arbitrage.

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

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

The description clearly implies when to use the tool: for daily bet discovery without paging through markets. It also provides operational context like the tradeable-edge knobs and the note about Fed bets being excluded from ranking. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond these: snapshots are written on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, and decay numbers come from daily closes rather than intraday. 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 but every segment earns its place: ARGS, RESPONSE, and LIMITS are clearly labeled and densely informative. It avoids fluff and packs all essential info into structured sections, making it highly scannable for an AI agent.

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 (time-series, expired opportunities, snapshot dates) and no output schema, the description fully explains the response structure and important caveats. It covers what data is returned, how to interpret trends, and limitations like TTL and data gaps, making it self-sufficient.

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

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

Schema coverage is 100%, with both params fully described. The description repeats days and window with defaults but adds only slight context like 'lookback' and 'snapshot family' that is already present in the schema. It does not materially add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the core question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge values.

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 context for when to use the tool: when you need to evaluate whether an edge is fresh or decaying, with the example 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies the alternative is polymarket_edges for snapshots, but does not explicitly state when not to use this tool or name alternatives directly.

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

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

Annotations already indicate readOnlyHint:true, but the description adds rich behavioral detail beyond that: it 'walks the ladder', returns fields like top_of_book, vwap_fill_price, slippage_pp, and warns about forced_directional_risk and thin_legs. 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 dense and information-rich, with clear mode sections and uppercase keywords, but it is a single long paragraph that could be better structured with bullets or subheadings. It earns its place but is slightly verbose.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It covers both modes, expected output fields, risk warnings, and usage context, including the most common failure mode. No critical information is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains side defaults per mode, size_usd interpreted as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional' in basket mode, plus the clamp range. This goes 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource statement. It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on whether theoretical edges are actually capturable given order-book depth.

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

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

The description explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why ('theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'). This is explicit when-to-use guidance.

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

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

With readOnlyHint, openWorldHint, and idempotentHint already present, the description adds substantial behavioral context: the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment implications (aligned:false means spreads are meaningless), and skipped_cross_type/subtype counters that reveal dropped comparisons. These go far beyond the annotations and are critical for interpreting 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 well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and a logical flow from purpose to invocation to response interpretation. Every section earns its place for a complex tool with no output schema, though the density could be overwhelming for a quick scan.

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

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

With no output schema, the description fully carries the burden of explaining the response: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It also explains when spreads are meaningful versus meaningless, giving the agent complete contextual guidance for a multifaceted tool.

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

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

The schema already covers all three parameters with 100% description coverage, so the baseline is 3. The description adds value by explaining the relationship between the topic shortcut and the explicit overrides (kalshi_event_ticker and polymarket_event_slug override the topic-mapped side), and it lists the ten macro shortcuts, complementing the schema's 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 opening sentence clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explicitly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads and even notes typical price gaps (2-25pp). This is a specific verb+resource+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?

The description thoroughly explains when to use topic shortcuts versus explicit ticker/slug overrides, and warns that most pre-mapped topics currently return compatibility_warning, emphasizing 'pre-mapped ≠ tradeable.' This gives clear context for when the tool is useful and its limitations, though it does not explicitly name alternative sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: scoping to an identifier (anonymous IP, BYO key hash, account ID), the ability to list all keys by omitting the key argument, and the pairing with remember/forget. This enriches the agent's understanding of the tool's behavior without contradicting annotations.

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

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

Three sentences, each contributing distinct value: function, usage context, and scoping/companion tools. No redundancy, front-loaded with the primary action, and free of extraneous detail. 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?

For a simple tool with one optional parameter and strong annotations, the description is complete. It explains both modes (retrieve by key, list all), when to use it, scoping, and sibling relationships. No output schema exists, but the description adequately conveys what the user gets back ('a value' or 'all saved keys'). No critical 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?

The input schema covers 100% of parameters with a clear description: 'Memory key to retrieve (omit to list all keys)'. The description essentially repeats the same information ('omit the key argument'), adding little semantic value beyond what the schema already provides. The bar is met but not elevated.

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

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

The description opens with a specific verb-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings like remember and forget by explicitly naming them and associating recall with retrieval. The purpose is unambiguous and the tool's scope is well-defined.

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

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

Provides explicit when-to-use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also pairs with remember and forget, indicating alternatives for save/delete operations, and mentions the optional key-omission behavior for listing all keys. This fully answers when and when not to use it.

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

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

Even with annotations present (readOnlyHint, idempotentHint), the description adds valuable behavioral details: it discloses the mark_read side-effect (flagging events as read so the next call shows newer ones), mention of a persisted feed written by the evaluator, and an alternative public URL. This goes beyond the annotations and gives the agent a clear understanding of state-changing behavior and data source.

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 and front-loaded: the first sentence immediately states the action and returns, the second sentence adds filtering and the mark_read behavior plus an alternative URL. Every sentence earns its place, with no fluff or redundancy.

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

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

With no output schema, the description sufficiently explains return values (source, citation_uri, raw event payload). It also covers filtering, polling behavior, and side effects. The tool is simple with 5 optional parameters all schema-documented, and the description fills any gaps, making it complete for agent use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by providing a concrete example for 'type' ('sec_8k') and explaining the effect of 'mark_read' on subsequent calls. It does not describe 'limit' or 'unread_only', but those are already clearly documented in the schema, so the added value justifies a 4.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the verb (pull), and distinguishes it from siblings like list_subscriptions or recent_changes by focusing on alerts/events. It also details return contents, making the purpose unmistakable.

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

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

The description provides clear context for when to use the tool: for polling alert events from the subscription feed. It also mentions an alternative method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, giving some guidance on scenarios. However, it does not explicitly compare to sibling tools or state when not to use it, so it stops short of a 5.

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?

Even with readOnlyHint=true and destructiveHint=false annotations, the description adds substantial behavioral detail: it fans out to multiple sources, explains GDELT→GNews fallback conditions, discloses USPTO soft-fail due to API sunset, and describes the return structure (changes[], total_changes, citation URIs). This goes well beyond the annotations.

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

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

The description is dense but every sentence earns its place: it includes usage examples, source specifics, fallback logic, parameter hints, return format, and an alternative tool recommendation. It is front-loaded and well-structured, with no irrelevant 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?

Given the tool's multi-source fan-out complexity and absence of an output schema, the description is remarkably complete. It explains all data sources, fallback behavior, parameter accepted formats, return structure, and when to use an alternative tool. No critical information appears missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, with each parameter already described in detail (type: 'company', since: ISO/relative, value: ticker/CIK). The description does not add new parameter-level meaning beyond what the schema provides; it mostly reinforces the `since` semantics and mentions return values, which is not parameter-specific. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: a change feed for a company in the last N days/weeks/months, covering SEC filings, news mentions, and patents. It uses specific verbs ('Fans out', 'Returns') and explicitly differentiates from the sibling tool entity_profile ('Use entity_profile instead when you want the static profile...').

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

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

The description provides explicit when-to-use guidance with example queries ('What's new with X' / 'latest on Y') and explicitly names the alternative tool to use for static profiles regardless of window. It also explains fallback behavior (GDELT preferred, GNews on rate-limit/5xx) which informs usage expectations.

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

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

Annotations already indicate write operation, idempotent, non-destructive. The description adds valuable context: persistence differs for authenticated vs anonymous users (24-hour retention), and memory is scoped by identifier. This goes beyond annotations without contradicting them, though it doesn't specify overwrite behavior for duplicate keys.

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

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

The description is compact and well-organized: primary action first, then usage guidance, storage details, and companion tools. Every sentence adds distinct value with no redundant 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?

For a two-parameter key-value store with complete schema documentation, the description covers the essential aspects: what is saved, when to use it, storage scope, retention policy, and how to interact with related tools. No output schema is needed for a save operation.

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

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

Schema coverage is 100% with descriptions for both key and value. The description reinforces the parameter purpose with examples (resolved ticker, target address) that largely mirror the schema's suggested values, adding minimal new semantic detail.

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

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

The description states a specific action and resource: 'Save data the agent will need to reuse later' as a key-value pair. It clearly distinguishes from sibling tools by naming recall and forget for retrieval and deletion, making the purpose unambiguous.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' and gives concrete examples like ticker or user preference. It also names the alternatives (recall to retrieve, forget to delete), giving clear when-to-use versus when-not-to-use context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: it cascades through multiple lookup endpoints, auto-disambiguates inputs, and returns citation URIs. This exceeds the annotation baseline and provides actionable behavioral expectations.

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 yet well-structured: starts with example intents, gives a clear directive, then details supported types and return formats. Every sentence contributes value with no fluff or redundancy.

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

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

Despite having no output schema, the description thoroughly specifies the return values for each entity type, expected input formats, and internal cascading behavior. It also covers when to use the tool, making it functionally complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the schema already explains both parameters in detail. The description reinforces but adds only marginal semantics, such as the 'auto-disambiguated' behavior for company type and the return fields. Since the schema does the heavy lifting, 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 uses a specific verb ('resolve') and resource ('user-spoken NAME to canonical identifier'), and opens with concrete example questions that clarify its purpose. It clearly distinguishes itself from siblings like entity_profile by emphasizing ID lookup rather than profile enrichment.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not explicitly mention when not to use or name alternative tools, but the directive is strong and context is clear.

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

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

Beyond the readOnly, idempotent, openWorld annotations, the description discloses how it works (probes each entity with ai_visibility_check), the ranking behavior, and the return format (score, confidence, signal density). This adds valuable procedural context without contradicting annotations.

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

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

Three concise sentences deliver purpose, method, use case, and output format. Every sentence earns its place with no redundancy or tangential detail.

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

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

For a multi-entity comparison tool with no output schema, the description adequately conveys high-level behavior and return structure. It could mention model/API key constraints or error edges, but the schema covers those details, making this sufficiently 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 input schema covers 100% of parameters with descriptive text, so the description's basic mention of entities ('your brand + N competitors') adds little beyond the schema. Baseline of 3 applies; no param info is missing.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, and explains the specific mechanics (probes with ai_visibility_check, ranks by score, surfaces most/least recognized). This distinguishes it from the sibling ai_visibility_check (single-entity) and generic 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?

Provides a concrete use case ('competitive AI-marketing audits') and implies the multi-entity scenario, but does not explicitly name alternatives or state when not to use this tool. Clear enough for an agent to select appropriately.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations, including partial failure degradation, the 5-30s potential delay for bundlephobia's first measurement, and the sources_failed field. No contradictions with annotations.

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

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

The description is dense but every sentence adds value: the core purpose, when to use, return fields, ecosystem limitation, and failure behavior are all covered. It is front-loaded with the primary function and structured logically, with no fluff.

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

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

With no output schema, the description fully explains the return format, listing all summary fields, advisory details, links, and alternative versions. It also covers edge cases like partial failures and timeouts, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already describes both parameters (package name with scoped packages accepted, version with default behavior). The description does not add new parameter-specific semantics beyond what the schema provides, but it does reinforce the NPM-only ecosystem constraint, which is a minor addition. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for evaluating whether to add an npm package, with specific verb ('scan') and resource ('dependency'). It distinguishes itself by detailing the two data sources (deps.dev and bundlephobia) and the exact question it answers, which differentiates it from sibling tools.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions, noting that non-NPM ecosystems should use deps.dev:version directly, giving clear guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond these by revealing the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), similarity metric (cosine), and a critical cap: 200K chars with truncation flagged. This is substantial added context about runtime behavior and 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 dense but well-organized: first sentence defines the core operation, second gives the use case and value proposition, third connects to a sibling, fourth details algorithm and constraints. Every sentence serves a purpose, with no fluff or repetition of schema fields.

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

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

For a tool with no output schema, the description covers inputs, return format (top-N passages with character offsets and similarity scores), an edge case (truncation over 200K chars with a flag), and the intended workflow alongside ask_pipeworx_grounded. This is sufficient for an agent to select and invoke the tool correctly without additional 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% with useful descriptions for text, limit, and query, including examples. The description adds extra semantic color by giving concrete text-source examples ('a SEC 10-K body, an article, a long tool result') and clarifying 'natural-language query,' which slightly goes beyond the schema. Baseline is 3; the added context justifies a 4.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from sibling tools by explicitly pairing with ask_pipeworx_grounded, positioning this as the 'search inside' step versus the grounding/response step. The scope and output (top-N passages with offsets and scores) are unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also describes a concrete workflow with an alternative/companion tool ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'), giving the agent clear decision logic.

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 only cover readOnly/destructive/idempotent hints. The description adds substantial behavioral detail: returns new subscription id, requires authentication, SMS has 10/day cap, webhook signing secret is returned once, and webhook auto-disabled after 10 failures. This goes well beyond what annotations provide.

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

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

The description is long but information-dense, with the core purpose in the first sentence. It's well-organized by type and delivery channel, and every sentence adds a necessary detail. Slightly longer than minimal but justified by the complexity of the 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 3 parameters, nested objects, and no output schema, the description covers return value, prerequisites, supported subscription types with examples, delivery behavior, and edge cases like SMS caps and webhook failures. This is nearly complete for an agent to invoke correctly.

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

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

Input schema has 100% parameter description coverage, so baseline is 3. The description adds examples for each subscription type and delivery channel, but most of this is also embedded in the schema's descriptions. It enriches but doesn't fundamentally expand 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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and mentions the return of a new subscription id, making the purpose unmistakable.

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

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

It gives clear context for when to use: requires a Pipeworx OAuth account, explains delivery channels, and notes phone verification for SMS. While it doesn't explicitly name alternative tools, the context is sufficient for an agent to know when to invoke subscribe versus list or unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing the return structure (category-bucketed example questions with tool+argument shape) and the effect of omitting vs. passing the topic parameter. It does not contradict annotations and provides behavioral context beyond the structured metadata.

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 earns its place. It front-loads with example user queries, then explains purpose, return value, parameter behavior, and usage priority. There is no filler or repetition; it is structured as a continuous, information-rich flow that remains easy to parse.

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

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

For a one-optional-parameter tool with no output schema and rich annotations, the description is complete. It explains the return format, parameter semantics, and when to use the tool in the broader workflow. It also places the tool among siblings by referencing the meta-tools it helps learn, making it fully contextual 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?

The input schema already describes the topic parameter with its allowed values and the meaning of omission ('Omit for a cross-category spread'), providing 100% coverage. The description repeats this with a few examples (finance, pharma, betting) but does not add significant new semantic meaning beyond what the schema already conveys. 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 states a specific verb+resource+scope: it is the onboarding entry point for finding example questions and the exact tools that answer them. It lists example user queries, the return format (category-bucketed questions with tool+argument shape), and clearly distinguishes it from siblings by positioning it as the first tool to use when learning what Pipeworx can do.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to focus with the topic parameter. However, it does not explicitly say when not to use it versus alternatives like ask_pipeworx or discover_tools, so it lacks full 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, idempotentHint, openWorldHint, and destructiveHint=false, so the agent knows this is a safe read operation. However, the description adds no additional behavioral context, such as return format, pagination, or edge cases, leaving the agent with only the annotations.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It lacks a verb and essential information, making it insufficient for an agent to understand the tool's function.

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 read-only tool with an output schema, a brief description might be acceptable, but the lack of clear purpose and parameter semantics makes this description incomplete. The agent cannot determine what inputs mean or what the tool returns without additional assumptions.

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 provides no parameter explanations. While owner and spender are self-explanatory, the 'contract' parameter is ambiguous and not clarified, and there is no guidance on valid values or formats beyond the example in the schema.

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

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

The description 'ERC-20 allowance' is a tautology that merely restates the tool name/title. It does not specify a verb or clearly indicate that the tool retrieves an allowance, and it fails to distinguish from sibling tools like token_balances or token_metadata.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or scenarios where this tool is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds no extra behavioral context such as what is returned or how contracts are handled. The description is a bare label, not a behavioral specification.

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?

'ERC-20 balances' is extremely concise but under-specified, resembling a fragment rather than a structured description. It saves words but sacrifices clarity, which is not true 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?

With three parameters, a required address, and no parameter descriptions, the description is far from sufficient for an agent to invoke the tool correctly. The output schema exists, but the description fails to explain input semantics or usage scenarios.

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 any parameters (address, chain, contracts). There is no compensation for the lack of schema documentation, leaving the agent without crucial input 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 'ERC-20 balances' identifies the resource and narrows it to ERC-20 tokens, but it lacks a verb and does not specify that balances belong to a given address. It partially distinguishes from siblings like token_allowance or token_metadata, but remains vague without stating it returns balances for the input address.

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?

There is no guidance on when to use this tool versus alternatives such as asset_transfers or token_metadata. The description provides no context, prerequisites, or exclusions, leaving the agent to guess the appropriate selection.

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

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

Annotations declare readOnly, idempotent, non-destructive, and openWorld, which already convey safety. The description adds the ERC-20 scope, clarifying that the tool only applies to ERC-20 tokens, a behavioral constraint not present in annotations. However, no additional behavioral details like return format or limitations 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 extremely short, but it is under-specified rather than concise. A single fragment does not earn its place; it sacrifices clarity and provides minimal information, similar to the 'Process' example.

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

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

Despite having an output schema and rich annotations, the description fails to state the operation or when to use the tool. With siblings like token_balances and token_allowance, the tool could be easily confused. The description is insufficient for an agent to select and invoke this tool correctly without further inference.

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 provides zero parameter-level information. The parameter names 'contract' and 'chain' are somewhat self-explanatory, but the agent is left guessing expected formats (e.g., whether chain is a chain name or ID, what contract address format is required).

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 is a fragment 'ERC-20 metadata.' with no verb or action. It restates the title with a token standard, but does not clearly state whether it retrieves, creates, or updates metadata. While it hints at a distinction from NFT metadata, it lacks a specific operation.

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 description does not mention exclusions, prerequisites, or sibling tools, leaving the agent without context for tool selection.

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

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

Beyond the annotations (write, idempotent, non-destructive), the description adds critical behavioral context: ownership enforcement for authorization and the soft-delete nature ('deactivated, not deleted') that preserves history in recent_alerts. This directly addresses what gets changed and under what constraints.

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 deliver the core action, an ownership requirement, and the data-retention behavior. No wasted words; the most important information is 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 single-parameter cancellation tool with strong annotations, the description covers the purpose, authorization constraint, and the non-destructive effect on historical data. The lack of output schema is acceptable given the operation's simplicity.

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

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

The schema already fully documents the single 'id' parameter including its source (returned by subscribe). The description only reiterates cancellation 'by id' without adding extra parameter meaning, so the schema carries the semantic weight.

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 'Cancel a subscription by id,' a clear verb+resource combination that precisely states the operation. It also specifies the ownership scope, which distinguishes this from generic unsubscribe actions and complements the sibling subscribe/list_subscriptions 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 does not provide explicit when-to-use or when-not-to-use guidance, nor does it name alternatives like list_subscriptions for checking active subscriptions. The mention of recent_alerts is a behavioral consequence rather than usage 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 readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context beyond this: the dual-path routing (SEC EDGAR + XBRL vs. grounded pipeline), the percent-delta math for financial claims, and the exact verdict categories returned. It does not contradict annotations and provides meaningful operational detail.

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

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

The description is long but information-dense, with each sentence contributing to understanding the tool's scope, routing, and return value. It is structured logically from user intent to internal execution to output. A slightly more bulleted format could improve skimmability, but the content is well-earned.

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, so the description fully covers return values: verdict types, actual value with citation, and reasoning. It also explains the two processing paths and includes example claims. It does not mention failure modes or edge cases, but for a read-only verification tool with only two parameters, it is sufficiently 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% for both parameters, so baseline is 3. The description adds extra meaning, especially for tolerance_pct: it explains the default is capped at 5, how it overrides implied wording, and gives concrete usage guidance (1–2 for hallucination detection). This goes beyond the schema's 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 uses explicit verbs like 'fact check', 'verify the claim that…', and 'confirm or refute', and specifies the resource as 'natural-language claim verification against authoritative sources'. It clearly distinguishes from sibling tools by focusing on verification rather than open-ended Q&A, and even mentions 'Replaces 4–6 sequential calls', indicating a unique composite 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 explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines two internal paths based on claim type. However, it does not explicitly name sibling alternatives or state when NOT to use it, 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.