Etherscan

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral traits: it is a probing action, free for Workers AI, requires API key for Anthropic (cost passed to user), and returns per-model data. This goes beyond annotations without contradiction.

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

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

The description is concise: two sentences front-loaded with the main purpose and outcome, followed by brief parameter notes. Every sentence provides essential information with no redundancy.

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

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

Given the tool's complexity (4 parameters, no output schema, annotations present), the description covers purpose, parameter nuances, use cases, and expected return structure (per-model score plus combined view). It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with each parameter having a description. The description adds extra context: default model, conditional requirement of _apiKey, and purpose of context parameter. This adds moderate 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 'probes one or more LLMs for what they know about a business/brand/product/topic and scores visibility (0-100) per model'. It uses specific verbs and resources, and clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' which focuses on scanning rather than probing and scoring.

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

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

The description provides context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs paid model usage. It lacks explicit 'when not to use' or comparisons to sibling alternatives, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds context beyond annotations: it routes across 5,529 tools, returns structured answers with pipeworx:// citation URIs, works on every tier, and is a single fast call. This enriches understanding without contradicting annotations.

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

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

The description is long but packed with high-value guidance: alternatives, trigger phrases, examples, and tier behavior. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured logically, though it could be broken into bullet points for easier scanning. Every sentence contributes to usage.

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

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

Despite no output schema, the description reveals the return type (structured answer with stable citation URIs) and explains its role as default entry point. It covers routing, alternatives, examples, and even news handling, making it sufficiently complete for a tool of this 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 all six parameters documented as aliases for 'question', each with a description. The description does not add parameter-specific semantics beyond the schema, but the examples in the schema and description illustrate valid question formats. Baseline 3 is appropriate since the schema carries the load.

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 answers factual questions by routing to verified sources and returning structured answers with citations. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research by naming them and describing when each should be used instead.

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: 'PREFER OVER WEB SEARCH', lists trigger phrases, gives concrete examples, and states 'START HERE for most questions'. Also explains when to step up to ask_pipeworx_grounded or deep_research, with exclusions for breaking news.

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 that routing improvements may be active live, results are compared against the stable router, and it falls back to nothing (i.e., it is a fully working router, not a stub). This adds valuable context about the tool's dynamic behavior and experimental nature without contradicting annotations.

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

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

The description is compact and information-dense, with each sentence earning its place. It front-loads the key fact (beta version), then explains current status, usage, and experimental nature without fluff or repetition.

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

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

Despite lacking an output schema, the description explains the tool's scope (universal router with 5,529 tools), its relation to the stable version, its experimental behavior, and that it is fully functional. This is sufficient for an agent to invoke it correctly, especially given the comprehensive parameter schema and annotations.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description does not add any parameter-specific semantics, but since the schema already fully covers the parameters, the baseline of 3 applies. The mention of 'same arguments' is redundant with the schema.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, but with candidate routing improvements when under test. This distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded siblings by framing it as the experimental edge of the same router.

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

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

Explicit guidance is given: use it exactly like ask_pipeworx when you want the newest routing, and it notes that currently no candidate is active so it matches ask_pipeworx exactly. This tells the agent when to choose this tool over the stable alternative and explains the experimental comparison 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses the exact response shape on success and failure, including the refusal reason enum, and the extra LLM call cost. 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 but well-structured: it front-loads the core purpose, then details return format, refusal reasons, and usage guidance. Every sentence provides useful information without redundancy, appropriate for a high-stakes 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?

There is no output schema, but the description fully specifies the success and failure return structures, refusal reasons, routing scale, and cost context. It is complete for the tool's complexity and leaves no significant gaps.

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

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

The input schema already documents all parameters with 100% coverage, including aliases for the 'question' field. The description adds no additional parameter semantics beyond what the schema provides, 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: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

The description explicitly states when to use the tool (when answers will be quoted, cited, or acted on) and when not to (prefer ask_pipeworx for casual lookups), and it names the alternative tool. The cost tradeoff of one extra LLM call is also mentioned.

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

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

Annotations only convey read-only, open-world, idempotent, and non-destructive traits. The description goes far beyond, detailing market resolution, classification, fan-out logic, response shapes, safety mechanisms (e.g., short-circuit on low confidence), and resolution rules. 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 lengthy but well-structured: summary, use cases, examples, response fields, and edge cases. It is front-loaded with the core purpose. While verbose, every section adds necessary context for a complex tool; minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains return values (result.market, analysis, evidence, match confidence, parent_event, news fields) and covers all major edge cases (low confidence, closed markets, wide spreads, cancellation rules). It leaves no practical gaps for an AI agent.

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

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

Input schema covers 100% of parameters with descriptions, but the tool description adds significant value: examples of market input formats, explanation of depth levels with fan-out examples, and detailed context on include_raw (file sizes, use cases). This enriches the schema information substantially.

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 'Research a Polymarket bet' with a specific verb and resource, and distinguishes from sibling tools like ask_pipeworx and deep_research by emphasizing the single-call fan-out to category-specific data packs. The examples and use cases further clarify its unique role.

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

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

The description explicitly lists when to use the tool: 'for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also covers edge cases and failure modes, such as low-confidence matches and closed markets, guiding proper usage.

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

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

Annotations indicate a safe, idempotent read operation. Description adds SEC EDGAR/XBRL source for companies, FAERS/FDA/trials for drugs, handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs — significant behavioral context beyond annotations.

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

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

Two dense paragraphs that are well front-loaded with user intents. Slightly verbose but every sentence serves a purpose; could be tightened slightly without loss.

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

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

Despite no output schema, description explains return format (paired data + citation URIs) and sorting. Covers behavioral aspects and distinguishes from sibling tools like entity_profile, making it complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds examples (tickers, drug names) and clarifies the 2-5 limit. For 'type', it details what data is pulled per type, adding meaning beyond the schema enum.

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 lists multiple user phrasings and explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call. It clearly distinguishes from siblings like entity_profile and specifies the data sources for each type.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides guidance on entity types. Lacks exclusion scenarios (e.g., when not to use), but the preference is strong and clear.

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

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

Annotations already convey safety profile, but the description adds substantial context: account and paywall requirements, output format (findings packet with verbatim evidence, confidence, source, fetched_at, citation), gaps[] that never invent data, contradictions[], hop field, citation_uri fetchability guarantee, semantic excerpting, and latency. 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 information-dense, with each section (account requirement, alternatives, purpose, output details, depth modes, timing) serving a clear function. It is front-loaded with the critical account requirement, though it slightly duplicates schema content for depth.

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 fully compensates by detailing the findings packet, gaps[], contradictions[], citation URI semantics, and timing. It addresses prerequisites, use cases, alternatives, parameter effects, output behavior, and performance—comprehensive for a research tool.

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

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

Schema covers 100% of params with detailed descriptions, so baseline is 3. The description adds meaning by explaining depth-level behavioral consequences (gap recovery, paid thorough tier, timing) and reinforcing that broad/multi-part questions are acceptable, going slightly 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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call', providing a specific verb, resource, and scope. It explicitly contrasts with ask_pipeworx and states it is NOT open-web search, clearly distinguishing 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?

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples. It also states when-not-to-use and alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', plus a fallback for unsigned-in users.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 somewhat long but front-loaded with the core purpose. Every sentence adds useful information, though it could be slightly more concise. Clear structure.

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 (discovery tool with rich annotations and full schema), the description sufficiently explains what it returns and how results are ready to call. No output schema needed. Complete for the use case.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new meaning beyond what the schema already provides (e.g., aliases are already documented). It mentions curated examples in output but not parameter details.

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

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

The description clearly specifies the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example domains and distinguishes from sibling tools by stating 'Call this FIRST when you have many tools.' The verb 'find' and resource 'tools' are explicit.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises to 'Call this FIRST when you have many tools.' It provides clear context for usage vs. 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 the annotations (readOnly, idempotent, non-destructive), the description adds rich behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), explains the patent source sunset and soft-fail, and details the return structure. There are 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 well-structured with example queries, a list of return fields, and clear input constraints. It is informative without being excessively verbose, though the multiple example queries could be consolidated slightly. Overall, it is concise enough for its purpose.

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

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

Despite lacking an output schema, the description fully explains the return values: CIK, company_name, recent_filings (up to 5 with URIs), fundamentals, patents (with sunset note), news (via GDELT→GNews), and LEI. It also covers input limitations (no names) and sources. This provides a complete mental model for an 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?

Schema coverage is 100% with both parameters documented. The description reinforces the schema by elaborating on the 'value' parameter (ticker/CIK with zero-padded CIK example) and explicitly states 'names not supported', which adds clarity beyond the schema. However, it largely repeats information already in the schema.

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

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

The description clearly states the tool's purpose as producing a 'full cross-source profile of a US public company' in one call. It lists specific outputs (CIK, filings, fundamentals, patents, news, LEI) and distinguishes itself by advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('when the user asks for a holistic view') and when not (names not supported, directing to 'resolve_entity' first). It also specifies input requirements (ticker or CIK) and the expected behavior (parallel call, soft-fail for patents). This covers both inclusion and exclusion conditions clearly.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds useful behavioral context: clearing sensitive data and pairing with other tools. No contradiction.

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

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

Two sentences, no wasted words. Front-loaded with purpose and usage. Highly efficient.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, and pairing with siblings. 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% with description for key parameter. Description does not add additional semantic information beyond schema, but 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?

Description clearly states 'Delete a previously stored memory by key', with specific verb and resource. Differentiates from sibling tools remember and recall by specifying deletion.

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 scenarios: stale context, task done, clearing sensitive data. Also pairs with remember and recall, giving alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context by stating it fetches the page and extracts content, which is consistent with these hints. No contradiction; missing details like rate limits are acceptable given 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 comprised of three efficient sentences, front-loaded with the core purpose. Every sentence provides necessary context with no extraneous wording.

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 annotations covering safety and idempotence, and the description explaining the use cases and output format (a single text blob), the tool is well-specified. The only minor gap is no explicit mention of error handling or edge cases, but overall it's 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 description coverage is 100%, so the baseline is 3. The description does not add new information beyond the schema for parameters; it only briefly mentions max_links in context. No extra value provided beyond what the schema already offers.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, explaining the process and output format. It distinguishes the tool from siblings by focusing on AI crawler indexing, which no sibling tool directly addresses.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. It does not explicitly state when not to use, but the context is clear enough for appropriate 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?

Annotations already provide read-only, open-world, idempotent, and non-destructive hints. The description adds value beyond annotations by clarifying default chain and accepted chain identifiers, but does not delve into other behavioral traits like caching or rate limits.

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

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

Two sentences with no wasted words. Front-loaded with the core purpose, followed by essential details on defaults and accepted inputs.

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

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

Given only 2 parameters with 100% schema coverage and an existing output schema, the description covers all necessary context: what it does, default behavior, and accepted inputs. No gaps remain.

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

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

Schema coverage is 100%, but the description adds meaning by specifying default behavior for the 'chain' parameter (defaults to Ethereum mainnet) and listing accepted chain slugs, which is not fully captured in the schema description.

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

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

The description clearly states the tool retrieves native-token balance for an address on EVM chains, with a specific verb ('Get'), resource ('balance'), and scope ('address on a supported EVM chain'). It also distinguishes from siblings like get_token_balance which handles ERC20 tokens.

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

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

The description indicates default behavior (Ethereum mainnet) and acceptable input formats (chain slug or numeric ID), implying usage for native token balances. However, it lacks explicit guidance on when not to use this tool versus alternatives like get_token_balance.

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 valuable behavioral context: the dependency on Etherscan verification and the output format (JSON), which are not in 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 a single front-loaded sentence with no extraneous words. Every word adds value, and the key information (what, format, condition) is immediately clear.

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

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

Given the tool has only two parameters with full schema coverage, annotations, and an output schema, the description suffices for a simple query tool. It could mention error handling for unverified contracts, but overall it is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema provides for the two parameters (chain and address). It mentions JSON output but no additional parameter details.

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

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

The description clearly states the tool retrieves the verified contract ABI as JSON. It specifies the resource (contract ABI) and verb (get), and distinguishes from siblings like get_contract_source which retrieves source code.

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

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

The description implies usage condition: only works for contracts verified on Etherscan. It does not explicitly mention when to use versus alternatives, but the sibling list shows distinct tools (e.g., get_contract_source), making context clear.

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

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

Annotations already indicate read-only, idempotent, not destructive. The description adds specific data fields returned (source code, compiler version, etc.), providing useful context beyond annotations.

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

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

Single sentence, no fluff, front-loaded with the key information about what the tool returns.

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

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

Given the presence of an output schema (not shown) and clear annotations, the description is mostly complete. However, it does not mention prerequisites (e.g., contract must be verified) or what happens if not verified.

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 parameters are documented. The description does not add extra meaning beyond the schema's parameter descriptions.

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

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

The description clearly states what the tool returns: verified contract source code, compiler version, optimization settings, and license. It distinguishes from sibling tool 'get_contract_abi' which returns ABI.

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

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

No explicit guidance on when to use vs alternatives. The purpose is clear but there is no description of when not to use or comparison with siblings like 'get_contract_abi'.

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 the tool is read-only, idempotent, and non-destructive. The description adds minimal extra behavioral context beyond specifying it queries an ERC-20 token balance. No contradictions.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose without any extraneous words or repetition.

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

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

The description covers the core functionality for a simple query tool. With an output schema available, it does not need to detail return format. However, it could mention the unit of the balance (e.g., wei) for full completeness.

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

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

The description adds semantic context that this tool is for ERC-20 tokens, complementing the schema descriptions that cover each parameter individually. Since schema coverage is 100%, baseline is 3, but the description provides a concise purpose statement tying parameters together.

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

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

The description clearly states the verb (get) and resource (ERC-20 token balance) with specific parameters (address, contract). It explicitly mentions ERC-20, distinguishing it from sibling tool get_balance which likely refers to native chain balance.

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 use case for ERC-20 tokens but does not explicitly state when to use this tool versus alternatives like get_balance. No exclusions or alternatives are mentioned.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by listing the returned fields and the optional parameter, enhancing transparency.

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

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

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

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

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

Given the simple tool with one optional parameter and clear annotations, the description is sufficient. It lists return fields and usage context. Could mention pagination but not critical.

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

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

Schema coverage is 100% with a single boolean parameter described. The description does not add meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'list' and the resource 'the caller's active subscriptions'. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't enumerate when not to use, the guidance is clear.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds the behavioral trait that 'type' controls which transaction subset is returned, which is valuable context beyond annotations.

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

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

Two sentences: first states the main purpose, second explains the key parameter. No wasted words, front-loaded with the essential action.

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

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

Given the 8 parameters and existing output schema, the description covers the core listing functionality. It doesn't detail pagination or sorting, but those are standard and documented in the schema.

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

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

Schema coverage is 100%, baseline 3. The description adds semantic value for the 'type' parameter by explaining what each enum value means (e.g., 'internal' for contract-internal transfers), which is not in the schema description.

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

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

The tool name and description clearly state 'list transactions for an address', specifying the action and resource. The 'type' parameter distinguishes five categories, and no sibling tool overlaps directly.

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

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

The description explains when to use each 'type' value, but does not explicitly mention when not to use this tool or point to alternative tools for balances or other queries. However, the context implies its use for transaction history.

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 being all false, the description discloses key behaviors: filing returns a claim_token, rate-limited to 5 per identifier per day, free and not counted against quota, and the team reads digests daily. It also specifies that only Pipeworx-served tools are accepted, which manages expectations. No contradiction with annotations.

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

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

The description is longer than average but every sentence provides operational value, and it's front-loaded with purpose and usage. The token flow and rate-limit details are necessary for correct invocation. It could be trimmed slightly, but the structure is clear.

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

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

For a non-trivial tool with a two-phase usage (file then claim_token read), the description covers the mechanics, exclusions, and rate limits. The lack of an output schema is mitigated by explaining what filing returns. It doesn't mention account-based behavior explicitly, but that doesn't prevent an agent from using the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter (type enum, context object, message, claim_token). The description adds minimal extra parameter-level meaning beyond the schema; for example, the claim_token flow is already described in the schema's claim_token description. It reinforces the 'don't paste end-user prompt' guidance but that's already implied by context. Baseline 3 is appropriate.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool as a feedback channel for Pipeworx. It distinguishes from siblings like ask_pipeworx (question answering) and discover_tools (catalog exploration) by focusing on reporting issues/praise about the service itself.

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 enumerates when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This is exemplary guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h. No contradictions.

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

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

Description is compact, with three short paragraphs: what it does, use cases, technical note. Front-loaded with main action. Every sentence adds value, no waste.

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

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

Given no output schema, description explains return content (top tools, top packs, total call volume). Parameter fully documented. Annotations cover safety. Simple read-only tool is fully described.

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

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

Schema covers the single parameter window with enum and description. The description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' and notes default 24h, going beyond schema.

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

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

Description clearly states the verb 'Returns' and the resource: top tools, top packs, and total call volume over a recent window. It distinguishes from siblings like discover_tools and ask_pipeworx by specifying it shows what other AI agents are calling.

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 lists three use cases (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't name alternative tools, the context is clear enough for an agent to decide when to use this versus other tools.

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

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

Goes far beyond annotations (readOnlyHint, etc.) by detailing algorithms, parameter behavior, fill checking, placeholder filtering, and Jaccard similarity threshold. No contradictions with annotations.

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

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

Well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with purpose. Slightly verbose due to repetition of partition check details, but every sentence provides value.

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

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

Covers all aspects: modes, algorithms, parameter usage, response structure, caveats (placeholders, similarity, fill check). No output schema, but description explicitly lists response fields, making it complete.

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

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

Schema coverage is 100%, and description adds significant meaning: explains expected formats (slug, topic seed), behavior of each mode, and that full URLs are accepted for event. Adds value 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to use each mode: trending scan with no args, specific market with event (recommended), cross-event scan with topic. Notes that cross-event mode catches patterns single-event misses. Provides guidance on fill check to avoid trading unrealistic edges. Lacks explicit comparison to sibling tools but 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the three response segments, edge computation formulas, filtering logic, caching behavior, and diagnostic output. There is no contradiction with annotations.

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

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

The description is long but well-structured with sections, bullet points, and clear organization. While verbose, the complexity of the tool justifies the length; it front-loads the core purpose effectively.

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

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

Given 9 parameters, no output schema, and complex behavior, the description is exceptionally complete: it explains segments, diagnostics, caching, edge computation details, Fed bets caveat, and filtering knobs, leaving minimal ambiguity.

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

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

With 100% schema coverage, the description adds substantial value by explaining the rationale for each parameter, e.g., slippage_pp context, min_partition_leg_kelly purpose, and category_filter options, enabling informed agent parameter choices.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and is distinguished from siblings like polymarket_arbitrage by its focus on discovering opportunities without paging through hundreds of markets.

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

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

The description explicitly says it is 'Built for what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. It provides implicit usage context but does not explicitly list when not to use it or direct to specific alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: history depth is bounded by a 60-day TTL, decay numbers come from daily closes (not intraday), and gaps exist on days without scans. This enriches the behavioral understanding beyond annotations.

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

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

The description is front-loaded with the key question and provides extensive detail on the response structure, which is necessary given no output schema. It is moderately concise but could be shortened without losing meaning.

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

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

Given the lack of an output schema, the description thoroughly covers return fields (tracked, expired, snapshot_dates), their semantics, and limitations. For a tool with moderate complexity, this is exceptionally complete.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description reinforces with default values and constraints (days default 14, max 30; window default '1wk'), adding clarity beyond the schema. However, it does not introduce new parameter meanings.

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: analyzing edge persistence and decay telemetry from daily snapshots. It differentiates between fresh and old wide edges, and provides detailed output fields, making the purpose unmistakable. This distinguishes it from siblings like polymarket_edges.

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

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

The description explains when to use this tool (to check how long an edge has existed and if it's shrinking) and contrasts the significance of a fresh vs. old edge. While it doesn't explicitly state when not to use it or mention alternatives, the context is clear and the sibling tools provide differentiation.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral details: walks order book ladder, returns verdict and fill metrics, explains basket mode risks like thin_legs and forced_directional_risk. No contradiction with annotations.

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

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

Well-structured with labeled sections, but slightly verbose. Every sentence is informative, but could be tightened slightly without losing clarity.

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

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

Despite no output schema, description fully documents return fields for both modes, including edge case detection (thin_legs) and risk warnings. Complete for agent usage.

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

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

All parameters have schema descriptions; description adds meaning (e.g., side default behavior, size_usd interpretation for buys vs sells and basket notion). Clarifies market vs event modes.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', with explicit modes (single-market and basket). It distinguishes itself from siblings by being a pre-trade risk check for arbitrage and edge signals.

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

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

Explicitly says when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why partial fills create directional risk, providing clear usage context.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds extensive behavioral detail: how the two modes work, the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped cross counters). This goes far 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 packed with necessary information but is relatively long. It is well-structured with clear sections (modes, response, safety fields). A slightly more concise formulation could improve clarity, but every sentence earns its place.

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

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

Given no output schema, the description compensates by describing the response structure (leg-by-leg prices, matched spreads, safety fields). It covers all key aspects for a spread tool. However, it could explicitly mention the datatype of response fields (e.g., array of objects) for completeness.

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

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

The schema already provides 100% coverage with descriptions for all 3 parameters. The description adds value by explaining the interaction between topic and explicit overrides, and providing examples. However, since schema coverage is complete, the description's incremental value is moderate.

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

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

The description clearly states it calculates cross-venue spreads between Kalshi and Polymarket, with two modes: pre-mapped topics and explicit event tickers. This specific verb+resource definition distinguishes it from sibling tools like `polymarket_arbitrage` which likely operates within a single venue.

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

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

The description provides explicit guidance on when to use each mode, warns that pre-mapped topics often aren't tradeable, and explains compatibility_warning and temporal_alignment to help agents decide when spreads are meaningful. It effectively tells when not to use the tool (e.g., when temporal_alignment:false).

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds that retrieval is scoped to the user's identifier and that the tool avoids re-deriving context. 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 two sentences, front-loaded with the core action, and every word contributes meaning. No redundancy or irrelevant details.

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 one parameter, no output schema, and rich annotations, the description provides sufficient context for basic usage. However, it does not specify the return format (e.g., string or list), which could aid agent understanding.

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

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

Schema coverage is 100% for the single parameter, and the description adds value by clarifying that omitting the key lists all saved keys, which is not obvious from the schema alone.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys if omitted. It uses a specific verb ('retrieve', 'list') and distinguishes itself from sibling tools like 'remember' (save) and 'forget' (delete).

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

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

The description explains when to use the tool ('to look up context the agent stored earlier') and mentions pairing with 'remember' and 'forget'. While it doesn't explicitly list when not to use or alternative tools, the context is sufficiently clear.

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

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

The annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds significant behavioral context: it specifies the exact data returned (source, citation_uri, payload), explains that mark_read flags events for the next call, and confirms polling is acceptable. It also mentions an alternative HTTP endpoint, providing extra transparency.

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 4 sentences and efficiently conveys the core purpose, return data, filter options, and mark_read behavior. The last sentence about the HTTP endpoint is slightly tangential but still useful context. It is well-structured and front-loaded with the main action.

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

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

Given the tool has 5 parameters and no output schema, the description provides adequate context: it mentions the return fields, filter parameters, mark_read effect, and polling suitability. It does not explicitly explain the limit parameter (covered in schema) or pagination, but the overall context is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for all 5 parameters. The description summarizes some parameters (type, since, mark_read) but does not add meaningfully beyond what the schema already provides. It restates mark_read's behavior which is already in the schema, so no significant added value.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns the most recent alerts with specific fields (source, citation_uri, raw event payload). This is a precise verb+resource description that distinguishes it from siblings like list_subscriptions (which likely manages subscriptions rather than retrieving alerts).

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

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

The description provides clear context: it mentions filter options (type, since), mark_read behavior, and notes that polls work fine and the same feed is available via HTTP. However, it does not explicitly say when to use this tool versus alternatives or when not to use it, missing some usage boundaries.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. Description adds context: fans out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail, and return structure with URIs. No contradictions.

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

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

Single paragraph, front-loaded with common queries, then explains functionality. No filler, every sentence contributes.

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, description still explains return structure and grouped sources. Complexity of multi-source tool is well covered. Sibling distinction provided.

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

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

Schema covers all 3 parameters with descriptions. Description reinforces `since` format and provides usage hint. Adds value 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 clearly states the tool provides a change feed for a company in a time window, with example queries and sources. It distinguishes from sibling 'entity_profile' by contrasting dynamic vs. 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?

Explicitly tells when to use this tool (change feed) and when to use 'entity_profile' instead. Also provides guidance on `since` parameter like '30d' for typical monitoring.

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

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

Description adds scope, persistence (authenticated vs anonymous), and pairing with other tools. Annotations already convey idempotent, non-destructive, read-write. Missing explicit mention of overwrite behavior on save, but overall good.

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

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

Description is concise, front-loaded, and every sentence adds value. No wasted words.

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

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

For a simple memory tool with no output schema, description covers use cases, scoping, persistence, and tool pairing. Complete enough for effective use.

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

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

Schema covers 100% of parameters with clear descriptions. Tool description adds usage examples but doesn't significantly expand beyond schema. Baseline score of 3 is appropriate.

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

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

Description uses specific verb 'save', identifies resource 'data the agent will need to reuse later', and gives concrete examples like resolved ticker, target address. It clearly distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Also pairs with recall and forget for retrieval/deletion, providing clear context.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: internal cascading through multiple endpoints, graceful degradation of LEI/FIGI enrichment, explicit labeling of each identifier with its source, and a guarantee that unresolved identifiers appear under `unresolved` rather than being omitted. This greatly exceeds what annotations alone 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 front-loaded with examples and a clear directive, then structured into SUPPORTED TYPES. It is longer than a simple one-liner but every sentence provides necessary detail about what is resolved and how data is returned. It strikes a good balance, though slight trimming could make it tighter.

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

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

With no output schema, the description carries the burden of explaining return values. It does so for company (CIK, ticker, company_name, LEI, FIGI, ownership, unresolved) and drug (RxCUI, ingredient, brand, citation). It also covers failure modes (source unavailability). It lacks a precise JSON structure, but for an agent selecting and invoking the tool, this is sufficient.

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

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

The input schema fully documents both parameters, including types, enums, and example values. The description adds helpful examples (e.g., tickers, CIK format, drug names) but does not fundamentally extend parameter semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with vivid examples and clearly states the action: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It distinguishes itself from siblings like entity_profile by focusing on name-to-ID resolution and explicitly positioning itself as the first step when an ID is needed.

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 usage guidance: "Use FIRST whenever you have a name but need an ID." It also clarifies what types are supported and when to use each (company vs drug). However, it does not mention when not to use this tool or name specific alternatives, so it falls short of a full 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses that it calls ai_visibility_check for each entity, ranks results, and surfaces most/least recognized. It also explains conditional model usage and API key requirements. This adds significant behavioral context not captured in 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, starting with the core action, then mechanics, then use case and return format. Every sentence adds value with no repetition or fluff.

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

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

Given the multi-entity, multi-model complexity, the description covers key aspects: ranking, fields (score, confidence, signal density), conditional API key, and context usage. It does not mention potential rate limits or pagination, but those are unlikely for a read-only probe. Still, the return format description compensates for missing output schema.

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

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

Schema coverage is 100% with descriptions for all parameters. The tool description adds extra semantics: first entity is treated as 'subject', models default to 'workers-ai', context applies to all probes. This enhances understanding beyond schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities by probing each with ai_visibility_check and ranking by score. It specifies the resource (AI visibility) and action (compare side-by-side), and distinguishes from sibling ai_visibility_check (single entity) by focusing on multiple entities. The use case example reinforces 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 gives a specific use case ('competitive AI-marketing audits') and implicitly differentiates from single-entity checks via ai_visibility_check. It does not explicitly state when not to use or list alternatives, but the context is clear. The note about first entity as 'subject' provides usage nuance.

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

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

Annotations already mark it as readOnly and idempotent. The description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. This provides useful context beyond annotations.

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

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

The description is a single paragraph that efficiently conveys purpose, usage, and behaviors. It is front-loaded with the main purpose, though slightly verbose in detailing return fields. Still, every sentence serves a purpose.

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

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

Without an output schema, the description lists return fields (summary block, advisories, links, versions). It also covers edge cases like partial failures and ecosystem limitations. Adequately 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 description coverage is 100%, and the description adds value by noting that scoped packages are accepted for 'package' and that 'version' defaults to latest. This extra guidance helps agents use parameters correctly.

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

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

The description clearly states the tool's purpose: a composite check for assessing npm packages, including license, advisories, and bundle size. It specifies the sources and distinguishes from other tools by noting ecosystem limitations.

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

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

The description explicitly says when to use the tool (e.g., 'is X safe / popular / small' or 'what does adding lodash cost me') and notes that it's for NPM ecosystem only, with alternatives mentioned for other ecosystems. No explicit when-not-to-use, but the context is clear.

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

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

The description discloses technical details such as the use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation and flagging. This adds substantial context beyond the annotations, which already indicate safe, non-destructive behavior.

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

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

The description is concise with five sentences, each adding value: it front-loads the core function, explains usage, details returns, pairs with a sibling, and includes technical specs. No unnecessary 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?

The description covers input, process, output (passages with offsets and scores), limitations (200K char cap), and integration with a sibling tool. It is fully self-contained for an AI agent to understand and use the tool effectively despite lacking an output schema.

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

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

With 100% schema description coverage, the description enhances parameter meanings by providing real-world examples (e.g., 'supply-chain risk') for the query parameter and explaining that text is a fetched document, adding practical context beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record,' providing specific verb and resource. It differentiates from siblings by explaining it pairs with 'ask_pipeworx_grounded' and is used when the record is too large for the prompt.

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

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

The description explicitly advises using the tool 'when the record is too big to cram into the prompt' and mentions the complementary sibling 'ask_pipeworx_grounded' for grounding over relevant passages, offering clear contextual guidance on when and how 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?

The description extensively covers behavioral traits beyond annotations: OAuth requirement, delivery constraints (SMS verification, 10/day cap), webhook auto-disable after failures, and one-time secret return. There is no contradiction with annotations (readOnlyHint=false, idempotentHint=true, etc.).

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

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

The description is lengthy but efficient, with front-loaded purpose. Every sentence adds necessary information. Given the tool's complexity (multiple subscription types and delivery channels), it remains readable without fluff. A minor improvement would be better structuring with bullet points.

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

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

Despite no output schema, the description mentions the return value ('Returns the new subscription id') and covers prerequisites, type-specific params, and delivery details. It omits explicit idempotency behavior (though annotations hint at it), but overall it is thorough 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 coverage is 100%, so baseline is 3. The description adds substantial value with concrete examples for each type (e.g., sec_8k items, fred_series series_id) and detailed delivery constraints (email validation, SMS matching, webhook signing). This goes beyond the schema's generic 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb (Create) and resource (subscription). It also distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides context about requiring a Pipeworx OAuth account and elaborates on delivery channels and type-specific parameters. However, it lacks explicit guidance on when to use this tool versus alternatives like 'recent_alerts' or 'list_subscriptions', leaving the agent to infer 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 indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral details: the tool returns category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog. 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 well-structured with front-loaded purpose. It is somewhat lengthy but each sentence contributes useful information (purpose, parameters, output, usage context). Could be slightly more terse, but effective.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and rich annotations, the description is fully complete. It covers purpose, parameters, output, and usage guidance without gaps.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing possible focus areas ('finance', 'pharma', etc.) and explaining that omitting the topic yields a cross-category spread. This enhances understanding beyond the schema's bare 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 uses specific verbs like 'returns category-bucketed example questions' and clearly identifies the tool as the onboarding entry point for a new agent. It distinguishes from sibling tools (e.g., ask_pipeworx, entity_profile) by stating its role in showing what to ask and how to call meta-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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and advises on calling with or without the topic parameter. It provides clear context but does not mention when not to use it or list alternatives explicitly, though the sibling tools imply alternatives.

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

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

The description discloses that the row is 'deactivated (not deleted)' and historical events remain via 'recent_alerts', adding significant behavioral context beyond the annotations, which already indicate non-destructive and idempotent.

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

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

Two sentences, front-loaded with the primary action, and no unnecessary words. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, behavioral effect, and links to a related tool, making it fully complete.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The description adds minimal extra meaning ('returned by subscribe'), which is helpful but not essential.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on when to use. However, it does not explicitly state when not to use or mention alternatives.

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

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

Annotations only give readOnly/openWorld/idempotent hints. The description adds deep behavioral context: the distinction between could_not_verify (check did not happen) and unsupported (no source found), explicit instruction not to show could_not_verify as evidence, and the two processing paths with exact percent-delta math. This greatly exceeds annotation coverage.

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

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

The description is long but every section has value: trigger phrases, routing rules, verdict list, and edge-case clarifications. It is front-loaded with the purpose and ends with the efficiency claim. It could be slightly tightened, but the structure is logical and not wasteful.

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

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

With no output schema, the description compensates fully by enumerating all six verdicts and explaining the ambiguous ones (could_not_verify, unsupported). It also covers both claim handling paths, the citation format, and the verification_error structure, making the tool's behavior and results predictable.

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 full descriptions and examples (claim and tolerance_pct). The description adds minimal parameter detail beyond the schema—mainly contextualizing the tolerance behavior—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 opens with trigger phrases and states 'natural-language claim verification against authoritative sources', clearly identifying the tool's verb and resource. It distinguishes itself from sibling tools by describing the SEC EDGAR fast path for company-financial claims and the grounded pipeline for all other claims, making its purpose unique.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' The description also explains how claims are routed (financial vs other) and clarifies when to expect certain verdicts (could_not_verify vs unsupported), providing strong guidance on invocation and interpretation.

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