Alchemy Eth

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

Annotations already indicate safe read-only behavior, and the description adds valuable context: default model, BYO key for Anthropic with payment on user's side, and return structure (per-model and combined view). No contradictions.

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

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

Two well-structured sentences front-load the verb ('Probe...and score'), then detail defaults, key parameter tradeoffs, and return format. 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?

Given no output schema, the description adequately describes return values (per-model fields and combined view). Parameter count and schema coverage are fully addressed, and the use cases are clear.

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 4 parameters have schema descriptions, and the description adds meaning beyond the schema: e.g., _apiKey is needed only if 'anthropic' in models, passed directly through; context can disambiguate; default model set.

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

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

The description clearly states the tool probes LLMs to score visibility (0-100) per model for an entity, distinguishing it from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on brand/topic visibility across multiple models.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model and API key requirements, but does not explicitly list when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that tool routes to 3,775 tools and returns structured answer with pipeworx:// citation URIs. No contradiction; adds meaningful 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?

Description is front-loaded with key guidance, but could be slightly more concise. Contains multiple sentences, each adding value (use cases, examples, output description). No wasted words, but length is justified.

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

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

Given tool's vast scope (3775 tools, 893 sources), description covers purpose, usage, examples, and output format (citations). No output schema, but description compensates. Could mention rate limits or authentication, but annotations already cover readOnly and idempotent.

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 6 aliases for the same parameter (question). Description lists aliases and says 'Your question or request in natural language.' This adds minimal meaning beyond schema, but is adequate. 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 the tool answers factual questions using authoritative structured data from 3,775 tools and 893 sources, distinguishing it from web search. It uses specific verbs like 'route' and 'return', and explicitly says 'PREFER OVER WEB SEARCH'.

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

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

Explicitly says to prefer over web search, lists many use cases (SEC filings, FDA data, etc.), and gives example queries. Provides clear when-to-use guidance with alternative explicitly mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: the tool ensures no hallucination by extracting answers only from tool results, returns explicit refusal reasons, and costs an extra LLM call. 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 a single informative paragraph that is front-loaded with the key purpose. It is efficient but could benefit from slightly more structure (e.g., bullet points for the return keys). However, it earns its length with substantive content.

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

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

Despite having no output schema, the description fully explains the return structure, including keys like answer, evidence, confidence, source, fetched_at, and all possible refusal_reason values. Given the complexity of the tool, this is highly 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% (all parameters described). The description does not add new parameter-level details beyond what the schema provides. Baseline score of 3 is appropriate as the schema already covers parameter semantics.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, specifying the routing and extraction process. It explicitly distinguishes from the sibling 'ask_pipeworx' by noting the extra LLM call and use case difference.

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 this tool (high-stakes, quoted/cited answers, factual decisions) and when to prefer the sibling 'ask_pipeworx' for casual lookups. It also notes the cost trade-off of an extra LLM call.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no behavioral context beyond a vague label, but does not contradict annotations.

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

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

Extremely short (3 words) but lacks substance. Conciseness is not valued when it omits essential information; the description is under-specified.

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

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

Given the tool's complexity (likely a blockchain transfer feed) and the presence of many sibling tools, the description completely fails to provide context, usage scenarios, or any differentiation criteria.

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 lists no properties (schema coverage 100% by default), so the description carries the burden of explaining the tool's behavior with zero parameters. 'Enhanced transfer feed' adds minimal meaning, failing to describe what the tool returns or accepts.

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 'Enhanced transfer feed' is a vague phrase without a verb or clear resource. It does not specify what transfers (e.g., tokens, NFTs) are covered, making it indistinguishable from sibling tools like nft_owners or token_balances.

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 usage guidance is provided. There is no mention of when to use this tool versus alternatives, nor any prerequisites or 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?

The description is highly transparent, detailing the full pipeline: market resolution, classification, parallel fan-out, response shapes with specific fields, resolver contract, parent event extractor, news fallback, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. Annotations (readOnlyHint, idempotentHint) are consistent.

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

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

The description is long but well-structured with clear sections (purpose, classifiers, fan-out examples, response shapes, etc.). It is front-loaded with the core purpose. While verbose, the complexity of the tool justifies the length.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It covers input handling, output structure, error cases (low confidence, closed markets), edge cases (illiquid spreads), and resolution risk. 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?

All three parameters are fully described in the input schema (100% coverage). The tool description does not add significant additional semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). The purpose is specific and distinct from siblings like polymarket_arbitrage.

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

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

The description explicitly says when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive examples but does not explicitly mention alternatives or when not to use it. However, the context is clear.

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

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

Annotations indicate readOnlyHint true, etc., and the description adds detailed behavioral context: sources (SEC EDGAR/XBRL, FAERS), data points, handling of off-calendar fiscal years, and response format with citation URIs, 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 detailed but well-structured, front-loading with natural language examples and a clear imperative. While slightly long, 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?

Despite no output schema, the description thoroughly explains return data (paired data + citation URIs, sorted by primary metric) and covers all necessary context for the tool's complexity, including data sources and edge cases.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining what each type retrieves, providing examples, and noting sorting behavior, going beyond the enum and array descriptions.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, with specific natural language triggers. It distinguishes between company and drug types, 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides clear context for when to use this tool versus alternatives, such as entity_profile or individual lookups.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds critical behavior: explicit gaps[] for unanswerable facets (no hallucination), time expectation (15-60s), and parallel routing mechanism. 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?

Description is comprehensive and well-structured, but slightly lengthy. However, 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?

Covers purpose, process, output format, usage guidelines, prerequisites, time expectation, and limitations. Complete for a complex tool without 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 has 100% coverage, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and payment requirement, and gives example for question parameter.

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

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

Description clearly states verb 'research' and resource 'multi-source', detailing parallel decomposition and grounded answer extraction. Specifically distinguishes from sibling 'ask_pipeworx' for single lookups.

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

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

Explicitly states use for broad/multi-part questions, advises using ask_pipeworx for simple lookups, and notes prerequisites: Pipeworx account and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, making the tool safe. The description adds that it returns top-N tools with full schemas ready to call, which is 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 front-loaded with the core purpose and is well-organized. It is slightly long but every sentence adds value, no redundancy.

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

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

Given no output schema, the description explains what is returned (tool names, descriptions, schemas) and how to use results. With 6 parameters explained in schema, the description is complete for effective use.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the query parameter is a natural language description and providing two examples, aiding correct invocation.

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 finds tools by describing data or task, with specific examples of use cases (SEC filings, stocks, etc.). It distinguishes itself from sibling tools which are specific operations by being a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available' and 'Use when you need to browse, search, look up, or discover what tools exist for: ...' providing clear when-to-use and implicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: parallel multi-source fetching, soft-fail for patents, GDELT→GNews fallback, and specific return fields. 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 thorough but front-loaded with example queries. While slightly long, every sentence contributes useful information, with a clear flow from usage to behavior to parameters.

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

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

Despite no output schema, the description details all returned fields (cik, filings, fundamentals, patents, news, LEI) and their sources, providing complete context 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?

Schema coverage is 100%. Description adds meaning by clarifying that type must be 'company', value is ticker or zero-padded CIK, and names are not supported—overcoming ambiguity.

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 precisely states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', listing specific sources and outputs, and distinguishes it from chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and advises using resolve_entity if only a name is available.

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 provide rich behavioral hints (readOnly, idempotent, non-destructive), but description adds no additional context. It does not explain side effects, permissions, or error handling.

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

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

Extremely concise (4 words) but at the cost of utility. Under-specification makes it ineffective, not concise.

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

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

Despite annotations and output schema, the description is too sparse for a tool with 3 parameters and broad applicability. Lacks instructions on method selection, param structure, or response handling.

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

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

Schema has 3 parameters with 0% description coverage. Description does not explain any parameter meaning or format. Examples in schema are not part of description. Agent gets no assistance.

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 is vague: 'Generic JSON-RPC call.' It does not specify which blockchain methods are supported or differentiate from sibling tools like token_balances or nft_metadata. While not a tautology, it lacks specificity.

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

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

No guidance on when to use this tool versus alternatives. Cannot infer from description alone; relies on agent's prior knowledge of JSON-RPC.

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 destructiveHint and idempotentHint. Description adds context about clearing sensitive data but doesn't elaborate on behavior for missing keys; still consistent and useful.

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 fluff, front-loaded with the core action and purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage context, and behavioral hints.

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 adequate parameter description. The tool description does not add additional parameter clarity beyond the schema.

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

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

The description clearly states the action (delete), the resource (memory by key), and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: context is stale, task is done, or sensitive data removal. Mentions pairing with siblings.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: fetches page, extracts title/description/key links, outputs markdown text. This goes beyond annotations by specifying the process and output format. No contradictions.

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

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

Two well-structured sentences front-load the main action followed by use cases. Every sentence earns its place; no filler.

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

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

All 2 parameters are fully covered by schema and description. Output is described as a single text blob. Annotations cover safety. No output schema needed; the description completes the picture.

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

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

Schema coverage is 100%, but the description adds value by clarifying the URL parameter examples and the max_links default/max values. It also implies the URL should be a site root or landing page. This enriches the schema's short 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 generates an llms.txt file for any URL, specifying the verb and resource. It differentiates from sibling tools by focusing on AI crawler indexing, and explicitly mentions use cases that distinguish it from related tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly lists three specific use cases (client site indexing, own project drafting, competitor auditing). It does not mention when not to use or alternative tools, but the provided context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by specifying return fields and the effect of the include_inactive parameter. No contradictions.

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

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

Two sentences, front-loaded with core purpose, no unnecessary words. Every sentence serves a purpose.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what the tool does, returns, and when to use it.

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

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

Schema coverage is 100% with a single parameter already well-described. The description does not add additional meaning beyond what the schema provides, 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?

Specifically states 'List the caller's active subscriptions' with clear verb and resource. Lists return fields and distinguishes from sibling tools like subscribe/unsubscribe by mentioning use cases for reviewing and canceling.

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 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context. Does not explicitly mention alternatives, but context is sufficient.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds no additional behavioral context (e.g., caching, data freshness, authorization). It minimally adds 'Single' to indicate one NFT, but that is already implied by the parameters.

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

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

The description is extremely short (4 words) but lacks necessary details for a tool with multiple parameters. It is underspecified, not concisely informative. A tool with 4 parameters and many siblings requires more structure to be 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?

Despite having output schema and rich annotations, the description is completely inadequate. It does not clarify the nature of 'metadata', parameter roles, or how this tool relates to sibling tools. This leaves the agent with insufficient information 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?

With 0% schema description coverage and 4 parameters (chain, tokenId, contract, refresh_cache), the description fails to explain any parameter meaning or usage. This is critical for correct invocation and falls well below the baseline.

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

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

Description 'Single NFT metadata' is essentially a tautology of the name 'nft_metadata'. It does not specify the tool's specific verb or resource beyond what the name implies, nor does it differentiate from sibling tools like 'nft_owners' or 'nfts_for_collection'.

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

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

No guidance is provided on when to use this tool versus alternatives. With numerous sibling tools (e.g., 'nft_owners', 'nfts_for_collection', 'token_metadata'), the description offers no context about appropriate use cases or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds no further behavioral context such as pagination, rate limits, or data freshness. It does not contradict annotations.

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

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

Extremely short, but under-specification is not conciseness. One fragment does not earn its place because it lacks necessary detail. A minimal viable description should at least include a verb and resource.

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 the presence of an output schema, the description is too vague to determine what 'owners' means (list of addresses, with balances?). For a tool with 3 parameters and read-only semantics, the description is incomplete.

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

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

Schema coverage is 0% (no descriptions in schema). The description does not explain any parameter (chain, tokenId, contract). It only implies that contract is central and tokenId is optional, but provides no format or role 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?

Description is a noun phrase ('Owners of a contract/token') rather than a verb indicating action. It vaguely hints at the resource but does not state what the tool does (list, get, query). Without a clear verb, the agent cannot easily understand the operation.

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

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

No guidance on when to use this tool vs alternatives like nfts_owned or nfts_for_collection. The description does not specify context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context (e.g., pagination via startToken, which parameters are optional, or how metadata inclusion works).

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?

Only 4 words, which is not concise but under-specified. The description fails to convey essential information, making it an inadequate spec rather than a helpful summary.

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

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

With 5 parameters, an output schema, and sibling tools, the description is grossly incomplete. It omits details about output format, pagination behavior, and how to use parameters like startToken or withMetadata.

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

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

Schema coverage is 0%, meaning no parameter descriptions exist. The description does not explain any parameter meaning (e.g., chain, limit, contract, startToken, withMetadata). The agent must infer from names alone, which is insufficient.

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

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

The description 'NFTs in a collection' barely adds to the name, providing no verb or clear action. It loosely indicates the resource but lacks specificity and fails to distinguish from sibling tools like nft_metadata or nft_owners.

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

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

No guidance on when to use this tool versus alternatives such as nft_metadata, nft_owners, or nfts_owned. The description gives zero context about usage scenarios or prerequisites.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behaviors. The description adds no additional context, such as pagination behavior, authentication needs, or error handling, leaving a gap in 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 a single sentence with no fluff, earning its place for basic purpose. However, it sacrifices detail for brevity, which is acceptable given its primary role.

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, multiple siblings, and an output schema, the description is too minimal. It fails to explain which blockchain is used, pagination, or how to filter by contracts, making it inadequate for complex 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?

With 0% schema description coverage, the description must explain parameter meanings, but it only mentions 'address' while the parameter is 'owner'. It does not clarify the other four parameters (chain, page_key, contracts, page_size) or their expected formats.

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 NFTs owned by an address, using a specific verb and resource. However, it does not differentiate from sibling tools like nft_owners or nfts_for_collection, which could cause confusion.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks explicit context for usage, and no exclusions or comparisons 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?

Beyond annotations (all false), description discloses rate limits (5 per identifier per day), cost (free, no quota), and impact (affects roadmap). 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?

Concise, well-structured paragraph. Every sentence adds information: purpose, when to use, how to describe, rate limits, quota. No fluff.

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

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

Given the simplicity of the tool, the description covers all necessary aspects: purpose, usage, constraints, rate limits, and team response. No output schema needed.

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?

Adds significant value over schema: explains enum values in detail, provides usage guidelines for each parameter (e.g., be specific, 1-2 sentences, 2000 chars max). Schema coverage is 100%, but description enriches it.

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: sending feedback about broken, missing, or needed features. It lists specific use cases (bug, feature/data_gap, praise) and distinguishes from sibling tools, none of which are for feedback.

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 (bug, feature, data_gap, praise) and what to avoid (don't paste end-user prompt). Provides clear context on describing issues and constraints.

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

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

Annotations already mark it as read-only and idempotent. The description adds value by disclosing the source (CF analytics-engine), no PII, and caching TTL (5min-1h), which helps manage expectations. 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 efficient: one sentence states the output, then a list of use cases, then implementation details. Every sentence adds needed context without redundancy.

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

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

Given the simple tool (1 optional param, no output schema, strong annotations), the description covers purpose, use cases, and internal details. It could specify the output format (e.g., list of objects with rank), but the current text is sufficient for most agents.

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 describes the window parameter and enum. The description adds comparative semantics ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing understanding beyond the schema.

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

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

The description clearly states it returns top tools, packs, and call volume over a window. It distinguishes from siblings like 'ask_pipeworx' (QA) and 'discover_tools' by focusing on trending aggregation.

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 three explicit use cases (hot data sources, canonical choice confirmation, alignment). It does not mention when-not-to-use or alternatives, but the use cases are specific enough to guide appropriate invocation.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, confirming safe, read-only behavior. The description adds rich behavioral context: the fill check (realizable_edge_pp vs theoretical_edge_pp_at_book), partition filter (drops placeholder slugs), and semantic anchor (Jaccard similarity ≥0.30). These details go 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 detailed and front-loaded with the requirement and modes. While some sentences are packed with technical jargon (e.g., 'deviations >3pp emit a BUY/SELL EVERY LEG signal'), all information serves a purpose. A slightly more streamlined structure could improve scannability, but it remains effective.

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

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

Given the lack of an output schema, the description thoroughly covers the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check details. It also includes error/edge cases like empty args fail and placeholder filters. For a complex tool with two modes and validation logic, this is completely adequate.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic'. The description enriches these with examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies mutual exclusivity, and explains the behavior of each mode. This adds significant 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 states the tool 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', using specific verbs and resources. It distinguishes between 'event' (single-event) and 'topic' (cross-event) modes, setting it apart from sibling tools like 'polymarket_edges' or 'polymarket_fill_risk'.

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

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

The description explicitly advises when to use each parameter: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also references an alternative tool: 'For custom sizing use polymarket_fill_risk'. However, it does not contrast with siblings like 'polymarket_edges' or 'polymarket_kalshi_spread', missing some context for agent decision-making.

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

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

The description extensively discloses behavioral traits beyond annotations: caching at KV level with 1-hour TTL, detailed model families and their inner workings, tradeable-edge knobs, and diagnostics for empty segments. Annotations only mark it as read-only, idempotent, and non-destructive; the description adds deep transparency about how edges are calculated and filtered.

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

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

The description is front-loaded with the core purpose but is very verbose with detailed model explanations. While thorough, it could be more concise or structured with bullet points. For a complex tool, the detail is justified, but some sentences are dense with technical terms.

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

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

Despite no output schema, the description thoroughly details the response structure (by_segment, fed_candidates, _diagnostics), explains caching, parameter interactions (e.g., min_partition_leg_kelly), and edge cases like Fed bets. It is complete enough for an agent to understand exactly what to expect and how to configure knobs.

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

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

Schema coverage is 100%, but the description adds significant meaning to each parameter, such as explaining slippage in context (zero fees but bid/ask eats 20-50bp), tradeable-edge filters like min_liquidity and max_spread_pp, and the purpose of min_partition_leg_kelly for partition arbs. Not every parameter gets extra context beyond schema descriptions, but overall adds 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's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It is specific about the verb 'scan' and the resource 'Polymarket markets', and differentiates from sibling tools like 'polymarket_arbitrage' by focusing on edge opportunities with the Pipeworx model.

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

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

The description provides clear context for when to use this tool ('what should I bet on today') and explains it helps discover opportunities without paging hundreds of markets. However, it lacks explicit guidance on when not to use it or direct comparison with sibling tools like 'polymarket_arbitrage' or 'polymarket_kalshi_spread'.

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?

All annotations (readOnly, openWorld, idempotent, not destructive) are consistent. The description adds context about snapshot gaps, TTL, and decay calculation, going beyond what annotations provide.

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

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

The description is long but well-structured, with early purpose statement, then args, then response fields. Some redundancy (e.g., days lookback mentioned twice) keeps it from a 5.

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

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

No output schema, yet the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and limitations (TTL, computation basis). Complete for a telemetry tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates defaults and clarifies the window parameter but does not add significant new information beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry, distinguishing from sibling tools like polymarket_edges by focusing on historical trends. It answers a specific question about edge age and 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 implicitly guides usage by contrasting fresh vs. old edges, but does not explicitly state when not to use or provide alternatives. The sibling list includes polymarket_edges, so 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: explains the two modes, how size_usd is interpreted differently, what the return values include (e.g., top_of_book, vwap_fill_price, verdict), and warns about forced directional risk. 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 long but well-structured with UPPERCASE headings (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded purpose. While every sentence adds value, slight verbosity prevents a perfect score.

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

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

Given the tool's complexity (two modes, multiple parameters, no output schema), the description fully explains all relevant aspects: mode activation, parameter differences, return fields, and key risks like partial fills and directional exposure. It is self-contained and comprehensive.

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

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

Schema has 100% coverage for all 4 parameters. The description adds extra meaning: for side, explains default and mode-dependent behavior; for event and market, clarifies which mode each activates; for size_usd, details single-market vs basket interpretation (spend, target proceeds, settlement notional). This goes well beyond the schema definitions.

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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and references sibling tools like polymarket_arbitrage and polymarket_edges, establishing a 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the risk of partial fills converting an arb into an unhedged position, providing clear when-to-use guidance.

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

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

Annotations indicate read-only, idempotent, not destructive. The description adds behavioral details such as the two modes, response fields (leg-by-leg prices, spreads), and safety fields (compatibility_warning, temporal_alignment). It does not contradict annotations and provides useful context beyond them.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose. While every sentence adds value, it could be slightly more concise without losing important 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 no output schema, the description fully explains return values (leg-by-leg prices, spreads, compatibility_warning). It covers behavior, edge cases (pre-mapped topics returning warnings), and safety fields. The context is thorough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%. The description adds significant meaning: it explains the two modes, lists all topic shortcuts, describes how explicit tickers override the topic, and warns that pre-mapped topics may not be tradeable. This goes well beyond the schema's basic property descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question. It specifies two modes (topic shortcuts and explicit tickers). However, it does not explicitly differentiate from the sibling tool 'polymarket_arbitrage', which likely has related functionality.

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

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

The description explains when spreads are meaningful (equivalent bet shapes) and alerts via compatibility_warning when they are not. It also mentions temporal alignment. However, it lacks explicit guidance on when to use this tool versus alternatives like polymarket_arbitrage.

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=true and idempotentHint=true. The description adds value by describing the listing behavior when key is omitted, scoping (anonymous IP, etc.), and pairing with other tools. No contradictions.

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

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

Three sentences, well-structured, front-loaded with the main action. Every sentence earns its place with no fluff.

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

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

Given the tool's simplicity and strong annotations, the description covers purpose, usage, scoping, and pairing completely. No output schema is needed for this read operation.

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

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

Schema coverage is 100% with a clear parameter description. The description adds meaning beyond schema by explaining the effect of omitting the key (list all keys) and mentioning scoping. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list) and resource (saved memory), and distinguishes from siblings like 'remember' and 'forget'.

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

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

The description advises when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use it, though 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?

Discloses that setting mark_read:true flags events as read, causing subsequent calls to return only newer alerts—this is a side effect that annotations (readOnlyHint: true) might not expect. The description is transparent about this behavior, adding value beyond annotations. However, the contradiction with annotations reduces overall clarity.

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?

Five short sentences, none wasted. Front-loaded with purpose, then returns, then filtering, then mark_read behavior, then alternative. Excellent structure and 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?

Covers main use cases (polling, filtering, marking read) and provides alternative access. However, it omits mentioning the 'unread_only' parameter and does not specify ordering of alerts. For a tool with 5 parameters and good annotations, this is a minor gap.

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. Description adds meaning by explaining how to filter (e.g., type example 'sec_8k', ISO timestamp for since) and the effect of mark_read. This goes beyond the schema descriptions, earning an extra point.

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

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

Description clearly states the tool pulls fired events from subscription feed, returns most recent alerts with specific fields. Verb + resource are precise, and it distinguishes itself by listing return elements (source, citation_uri, raw payload) and filtering options.

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 'Polls work fine' and provides an alternative URL for scripts/dashboards, giving clear context for when to use the tool vs. other access methods. Does not compare with sibling tools like list_subscriptions, but the alternative is well-defined.

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 readOnly and idempotent, but description adds valuable behavioral details: parallel fan-out, fallback logic, soft-fail for USPTO, and structured return format with citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads example queries and packs all necessary information (sources, fallback, return structure) without 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?

Even without an output schema, the description adequately explains the return structure (changes[], total_changes, URIs) and edge cases (API sunset, rate limiting). The tool is complex, but the description covers it comprehensively.

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 parameter descriptions. The description adds practical context: since accepts ISO dates or relative shorthand with examples, and value can be ticker or CIK. This adds clarity 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 uses specific verbs like 'change feed' and 'fans out to' with resource details (SEC EDGAR, GDELT, USPTO). It clearly distinguishes from sibling tool 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?

The description explicitly states when to use the tool (e.g., 'What's new with X') and when not to ('Use entity_profile instead...'). It also provides fallback behavior from GDELT to GNews.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context about persistence (authenticated users vs anonymous, 24-hour retention) and scope by identifier.

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

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

Three concise sentences plus a final pairing note. No redundant words, front-loaded with purpose. Efficient and well-structured.

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

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

Fully covers tool purpose, usage, persistence behavior, and scope. No output schema needed. Complete for a simple write 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 provides 100% coverage with descriptions for key and value. Description adds practical examples for key format and clarifies value type as 'any text', enhancing understanding beyond schema.

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

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

The description clearly states the tool saves data for later reuse, with specific verb 'save' and resource 'memory'. It distinguishes from siblings like recall and forget by explicitly mentioning them.

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

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

Explicitly advises when to use: 'when you discover something worth carrying forward'. Also mentions pairing with recall and forget, giving 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral detail: internal cascading through several endpoints, auto-disambiguation for companies, and output including citation URIs. 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 concise, front-loaded with purpose and examples, and every sentence adds value. It is well-structured, covering usage, supported types, input/output details, and internal behavior without redundancy.

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

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

Given the tool's complexity (two entity types, no output schema), the description fully explains inputs, outputs, and internal cascading. It covers return values including citation URIs and disambiguation, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100% (both parameters documented), so baseline is 3. The description adds extra meaning: for company value, it accepts ticker, CIK, or name with auto-disambiguation; for drug, brand or generic name. It also details output format per type, exceeding baseline.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific examples like ticker, CIK, and RxCUI. It distinguishes itself from siblings by focusing on entity resolution, and explicitly lists supported types and what they return.

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 advises 'Use FIRST whenever you have a name but need an ID', providing clear context. It gives example queries and notes that each call replaces multiple manual lookups, but does not explicitly exclude scenarios where it should not be used.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details (probing each entity, ranking by score) and notes the requirement of _apiKey for anthropic model, which complements the safe profile.

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 plus a brief explanation. It front-loads the main action and includes relevant context (example use case, output elements). 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?

Given the tool's moderate complexity (4 params, no output schema), the description covers the main behavior, output structure (ranked list with score, confidence, signal density), and use case. It lacks detailed output format, but annotations assure idempotence and safety.

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 minimal value beyond schema: it clarifies that 'context' disambiguates common names and that 'entities' first entry is the subject. However, it does not add new parameter information not already in schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking. It distinguishes itself from the sibling tool ai_visibility_check (single entity) and compare_entities (generic compare) by specifying the internal probe and ranking 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 says 'Useful for competitive AI-marketing audits' and provides an example question. While it doesn't explicitly state when not to use, the context implies ai_visibility_check is for single probes. Sibling tools also provide alternatives.

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

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

Beyond annotations (readOnly, idempotent), the description discloses behavioral traits: fans out to external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed lists timeouts. This informs the agent of potential latency and failure modes.

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

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

The description is well-structured with clear sections: purpose, usage, return fields, ecosystem scope, and edge-case behavior. It is informative without excessive length, though slightly verbose in listing all return fields.

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

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

No output schema is provided, so the description fully covers return values (summary block, per-advisory detail, links, alternative versions). It also notes NPM-only scope and graceful degradation, making the tool's behavior and limitations 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%, and the description adds context: 'Scoped packages accepted' for package, and clarifies that version defaults to latest when omitted. This enriches 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 opens with a clear composite purpose: 'Composite should I add this npm package to my project check in ONE call'. It specifies the tool fans out across deps.dev and bundlephobia, and notes the NPM-only scope in v1, distinguishing it from sibling tools for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also directs non-NPM queries to deps.dev:version directly, providing clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond that: explains return structure (top-N passages, character offsets, similarity scores), technical details (BGE-base-en embeddings, cosine over 500-char overlapping windows), and constraints (200K char cap with truncation flag). 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?

Single paragraph is well-organized: starts with purpose, then use case, then technical specifics. Every sentence adds value. Minor benefit could be splitting into bullet points for clarity, but it's already concise and front-loaded.

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

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

Despite no output schema, the description fully explains return values (passages, offsets, similarity scores) and tool behavior (windowing, truncation, pairing with ask_pipeworx_grounded). It covers everything an agent needs to understand when and how to invoke the tool, including limitations.

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 (100% coverage), so baseline is 3. Description adds value by explaining 'text' as fetched record, elaborating on 'query' with examples, and mentioning the limit parameter defaults and cap. It enriches understanding beyond schema without being redundant.

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 'Semantic search INSIDE a fetched record,' using a specific verb ('search') and resource ('a fetched record'). It provides concrete examples like SEC 10-K, article, and long tool results, and differentiates from siblings like ask_pipeworx_grounded by emphasizing offsets and context saving.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns passages with offsets for verification). It pairs with ask_pipeworx_grounded and suggests a workflow, providing clear guidance on when to use this tool versus alternatives.

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

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

Adds significant behavioral context beyond annotations: mutation (creates subscription), account requirements, delivery channel limitations (SMS 10/day cap, webhook auto-disabled after failures), and that webhook signing secret is returned only once. 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 clear sections: core purpose, requirements, types, delivery channels. Information-dense but each sentence adds value. Slightly lengthy but not wasteful; could be slightly more concise but effective.

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

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

For a creation tool with no output schema, the description covers purpose, required auth, type-specific parameters, delivery channels with limitations, and return value (subscription id). Completes the picture for selecting and invoking 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%, but description adds rich examples, constraints, and explanations for each type's params (e.g., items codes for sec_8k, sponsor/condition requirement for clinical_trial) and delivery options, significantly enhancing understanding.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream, returns new subscription id, and lists supported types and delivery channels. Distinguishes from sibling tools like list_subscriptions and unsubscribe through its creation action.

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 when to use: for proactive monitoring of live-data events. Includes requirements (Pipeworx OAuth account) and constraints (SMS cap, webhook auto-disable). Does not explicitly state when not to use or list alternatives among siblings, but the context of siblings makes the usage clear.

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

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

Annotations already provide safety profile (readOnly, idempotent, openWorld). Description adds value by detailing return structure: category-bucketed example questions with exact tool+argument shapes from a live catalog.

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 purpose, then details outputs and usage. Could be slightly more structured but is efficient and clear. No unnecessary words.

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

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

Given simplicity (1 optional param, no output schema) and high annotation coverage, description is complete. Explains return value, use case, and when to invoke. Siblings are many but this is clearly the onboarding tool.

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

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

Schema coverage is 100%, but description adds context: omitting topic gives full spread, passing it focuses on a specific area. Gives example values like 'finance', 'pharma', 'betting' beyond schema's list.

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 it's an onboarding entry point returning category-bucketed example questions with tool calls. Specifies verb 'returns' and resource 'example questions', differentiating it from siblings like ask_pipeworx and discover_tools.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to pass a topic and how it differs from meta-tools. Includes when-not-to-use by implication.

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 rich annotations (readOnlyHint, idempotentHint), the description adds no behavioral context beyond the tool name. It fails to explain what the tool does or what the return value represents.

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

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

Extremely concise but under-specified. A single phrase that is insufficient to convey tool function. Conciseness is not justified when it sacrifices 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?

Description is minimal despite the presence of an output schema and annotations. It does not explain what the tool returns or provide enough context for proper use.

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

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

Schema description coverage is 0%, and the description provides no parameter details. Parameters like owner, spender, contract are named but not explained, leaving the agent to infer their meaning.

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

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

Description is merely 'ERC-20 allowance' which restates the tool name without specifying an action. It lacks a verb and does not distinguish from sibling tools like token_balances or token_metadata.

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

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

No guidance on when to use this tool versus alternatives such as token_balances or token_metadata. The description does not provide any context for appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context, such as state changes, permissions, or rate limits, 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?

At three words, the description is under-specified rather than concise. It lacks essential detail and does not earn its extreme brevity.

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

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

Given the complexity (3 parameters, some optional) and the existence of an output schema, the description should at least hint at the input scope and output structure. It only states 'balances', leaving agents to infer the rest.

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

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

The schema has 0% description coverage for its 3 parameters. The description 'ERC-20 balances' does not explain what chain, address, or contracts represent or how they affect the query. This is insufficient for an agent to correctly fill parameters.

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

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

The description 'ERC-20 balances' clearly states the tool retrieves token balances, specifying the resource type. However, it is vague and doesn't distinguish from sibling tools like token_allowance or token_metadata, which could also relate to token information.

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

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

No guidance is provided on when to use this tool versus alternatives like token_allowance or entity_profile. There is no mention of context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral details such as what metadata fields are returned, potential errors, rate limits, or data freshness. The description does not add value beyond the annotations.

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

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

The description is extremely concise at two words, but this brevity sacrifices completeness. It does not provide a clear, self-contained statement of what the tool does. A description should be concise yet informative; this is under-specified.

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

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

Given the existence of an output schema (not visible here) and two parameters, the description should at least hint at the output structure or constraints. The current description is too sparse to be considered complete for an agent to understand the tool's full behavior and expected results.

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

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

Schema description coverage is 0%, meaning the input schema provides no descriptions for 'chain' or 'contract'. The description 'ERC-20 metadata' does not clarify the meaning of these parameters, e.g., that 'contract' is the token address and 'chain' may indicate the network. The description fails to add meaning beyond the schema parameter names.

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

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

The description 'ERC-20 metadata' indicates the tool returns metadata for an ERC-20 token, but it is vague about what metadata includes. It does not differentiate from sibling tools like token_allowance or token_balances which also deal with ERC-20 tokens. The title 'Token Metadata' reinforces the purpose, but lacks specificity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description is just a noun phrase with no context about typical use cases, prerequisites, or scenarios where this tool is appropriate. This is insufficient for an agent to decide between similar tools.

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

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

Annotations provide mutation information (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds valuable context: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. 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 consists of two sentences, each serving a distinct purpose: stating the action and qualification, and explaining the behavioral effect. No redundant or unnecessary information.

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

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

Given the tool has a single parameter, no output schema, and annotations present, the description is fully adequate. It covers the operation, ownership constraint, and side effects, leaving no ambiguity 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?

Schema coverage is 100% and the description adds meaning to the 'id' parameter by noting it is a UUID returned by subscribe. It also implies the id corresponds to the user's own subscription, adding ownership context beyond the schema.

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

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

The description clearly states the action (cancel/Unsubscribe), the resource (subscription), and the method (by id). It distinguishes from sibling tools like subscribe and list_subscriptions by referencing ownership and deactivation 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 ownership enforcement ('only cancel your own subscriptions'), which is a key usage condition. It also clarifies the deactivation behavior, but does not explicitly mention when not to use the tool (e.g., for complete deletion).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: it uses SEC EDGAR + XBRL, returns a structured verdict with citation and percent delta, and is limited to v1 company-financial claims. 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 concise yet comprehensive, starting with natural language triggers, then stating purpose, domain, functionality, return values, and efficiency gain. Every sentence serves a purpose. Minor improvement could be stricter separation of concerns, but overall well-structured for its length.

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

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

Given the tool's moderate complexity (single parameter, no output schema), the description fully covers the return format (verdict, structured form, actual value, citation, delta), the data source (SEC EDGAR + XBRL), and the current limitations (v1, US public companies only). No gaps remain for an agent to use it correctly.

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

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

There is only one parameter (claim) with 100% schema description coverage. The schema description already explains the parameter format with examples. The tool description further clarifies the types of claims it can handle (company-financial), adding context beyond the schema. This extra value lifts the score above the baseline of 3.

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

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

The description clearly identifies the tool's purpose: verifying natural-language factual claims against authoritative sources. It provides multiple example phrasings ('Is it true that...', 'fact check') and specifies the domain (company-financial claims for US public companies). This distinguishes it from sibling tools like ask_pipeworx, which handle more general queries.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the supported claim types (company-financial) and notes that the tool replaces multiple sequential calls, implying it should be preferred over manual decomposition. However, it lacks explicit when-not-to-use guidance or direct alternative tool references.

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