Blockchair

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds that it returns balance and recent transactions, which is useful output context. However, it does not disclose additional behavioral traits such as supported chains, pagination, or error handling. Given the strong annotation coverage, a score of 3 is appropriate.

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

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

The description is a single phrase, 'Address dashboard (balance + recent txs).' It is extremely concise with no filler words. Every word contributes meaning, making it appropriately sized 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?

The description states the core function and output, and an output schema exists, so return values are covered elsewhere. However, it lacks usage context, supported chains, and parameter format details. For a simple two-parameter tool with strong annotations, this is adequate but not complete. The 0% schema coverage and lack of guidance prevent a higher score.

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

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

Schema description coverage is 0%, and the description does not mention either parameter (chain, address) or their expected formats. The parameter names are self-explanatory, but the description fails to add any meaning beyond the schema, which itself lacks descriptions. This is a significant gap that the description does not compensate for.

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

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

The description 'Address dashboard (balance + recent txs)' clearly indicates this tool retrieves a dashboard view for an address, including balance and recent transactions. It distinguishes from sibling tools like 'block' and 'transaction' by focusing on the address resource. However, it lacks an explicit action verb like 'fetch' or 'get', making it slightly less precise.

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

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

The description provides no guidance on when to use this tool versus alternatives. The sibling list includes related tools such as 'block', 'transaction', and 'entity_profile', but no exclusions or preferred contexts are mentioned. The word 'dashboard' implies a summary view, but that is not enough to guide selection.

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

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

The description goes beyond annotations by disclosing that it probes external LLMs, that the default model is free, that passing _apiKey routes calls to Anthropic with direct billing to the user, and it specifies the return structure (score, confidence, signals, raw_response). This adds meaningful behavioral context.

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

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

Three sentences each serve a purpose: core function, model/key behavior, and return format with use cases. It is front-loaded with the main action and contains no redundant text.

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

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

Since there is no output schema, the description properly explains the per-model return fields and combined view. It also covers default behavior, optional key requirements, and relevant use cases, making it complete for a read-only probe 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?

All four parameters already have descriptive schema entries, so the description adds only minor specificity (e.g., naming Workers AI Llama-3.3-70b as the default). With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model, which is a specific verb+resource. However, it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, so it falls short of the top criterion.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default versus BYO-key workflow, but it does not explicitly name alternatives 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 cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful constraints: it routes the question, fills arguments, returns a structured answer with stable pipeworx:// citation URIs, and is a single fast call. It also warns that for 'what's the world saying' it routes to live news. This goes beyond annotations without repeating 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 longer than typical, but every sentence earns its place by providing guidance, examples, or alternative-tool differentiation. It is front-loaded with the key instruction to prefer it over web search and uses clear structure with 'START HERE' and 'Step up only when needed'. Slight verbosity prevents 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?

Despite having no output schema, the description explains the return format (structured answer with citation URIs), lists extensive example queries, details when to use alternatives, and notes it works on all tiers. It is fully sufficient for an agent to invoke the tool correctly in most scenarios.

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

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

The schema already describes the 'question' parameter and its aliases with 100% coverage. The description adds no additional parameter-level semantics beyond repeating that it accepts natural language. Baseline 3 is appropriate because the schema carries the weight.

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

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

The description clearly states that ask_pipeworx routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly mentioning alternatives like ask_pipeworx_grounded and deep_research, and by saying it is the default entry point. The verb 'ask' plus resource 'pipeworx' is specific.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a long list of factual topics, 'START HERE for most questions', and 'Step up only when needed' for alternatives. It also includes concrete example queries and notes it works on every tier, making the usage context unmistakable.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description reveals the experimental behavior: candidate routing improvements may be enabled live, the current state (no candidate active), and that it falls back to nothing but is a full working router. This is rich, specific behavioral context that helps the agent understand potential variability.

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

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

The description is three sentences, compact but information-dense. It front-loads the beta identity and immediately specifies identical scope, then explains current status and usage. No filler; every sentence contributes critical detail.

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

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

Given no output schema, the description references 'same response shape' as ask_pipeworx, which is useful but not self-contained. It thoroughly explains the beta status, current equivalence, and experimental purpose, making it sufficiently complete for an agent to decide to invoke it, though it relies on sibling knowledge for full response details.

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

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

The input schema provides 100% coverage, documenting all six parameters as aliases for 'question'. The description adds no additional parameter-level detail beyond saying 'same arguments', but the schema already fully explains the single meaningful parameter, so the baseline of 3 applies.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself as the experimental edge, making its purpose and relationship to the stable ask_pipeworx clear.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router to decide merges. This provides clear context, though it does not explicitly state when NOT to use it (e.g., if stability is critical) beyond describing its experimental nature.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the answer is extracted ONLY from tool result content, lists specific refusal reasons (not_in_source, no_tool_match, etc.), and reveals the extra LLM call. These are valuable behavioral traits not available from annotations alone.

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

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

The description is information-dense and well-structured, covering mode, routing, behavior, return schema, use cases, and cost. Every section contributes meaning, though the specific count of '5,529 across 1455 sources' is slightly verbose and could be condensed without losing value.

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

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

With no output schema, the description compensates by fully specifying the success and refusal response shapes, including evidence fields and refusal reasons. It also covers cost, use context, and failure modes, making it complete for an agent to select and invoke the tool confidently.

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

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

The schema already covers all six parameters with descriptions identifying them as aliases for 'question.' The description adds no further parameter-specific semantics (e.g., question formatting or limitations) but does imply the question should be high-stakes. Since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates from ask_pipeworx, indicating a distinct grounded mode. It clearly states the tool's function (grounded answer extraction) and resource (Pipeworx's 5,529 tools), making it distinguishable from sibling tools.

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

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

Directly provides when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also states when not to use: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off of an extra LLM call. This is explicit, actionable guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds far beyond this: resolver confidence thresholds, parent-event extraction, news fallback behavior, low-confidence short-circuits, closed-market handling, wide-spread tradeability flags, and cancellation-rule risk. This is rich behavioral context that the annotations do not 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 clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and use cases before diving into details. Some redundancy exists (e.g., repeated safety mentions), but overall every section earns its place for a complex tool.

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

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

This tool has no output schema, so the description carries the full burden of explaining return shapes. It covers all critical dimensions: market match confidence, alternatives, parent-event partitions, news fallback, safety blocking behavior, closed-market handling, illiquidity warnings, and resolution-rule risk. It is exceptionally complete for the tool's complexity.

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

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

Schema coverage is 100% with detailed field descriptions for market, depth, and include_raw. The tool description itself does not add parameter-level semantics beyond what the schema already says, but it does provide context on fan-out and response size indirectly via the include_raw schema. Baseline 3 applies because schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's scope and gives concrete usage examples. While it doesn't explicitly name sibling alternatives, the unique fan-out behavior and purpose distinguish it from related 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 'Use for' guidance is provided with three example intents ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). The description also gives classifier categories and fan-out examples, but it does not explicitly mention when NOT to use this tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the detail that lookup is by hash or height, which is more about input semantics than behavior. It does not disclose what 'details' specifically include, but with annotations covering the safety profile, the description provides acceptable incremental value.

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

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

The description is a single short sentence that directly states the tool's function. It is front-loaded and every word earns its place, with no fluff or redundancy.

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

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

Given the low complexity, existing output schema, and annotations, the description is minimally viable but still incomplete. It lacks usage guidelines and does not explain the chain parameter, which an agent needs to correctly invoke the tool. It is adequate for a simple lookup but leaves clear gaps.

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

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

Schema description coverage is only 50%: only hash_or_height has a description, while chain is undocumented. The tool description repeats the hash-or-height concept already present in the schema and offers no clarification for the chain parameter. It fails to compensate for the missing schema description on chain.

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 'Block details by hash or height' clearly identifies the resource (block) and the two primary lookup methods. It distinguishes itself from sibling tools like transaction and address by specifying hash or height lookup, though it lacks an explicit verb like 'Get' or 'Fetch'.

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 such as transaction or address. The description does not mention any context, exclusions, or alternative tools, leaving the agent to infer 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: performs one parallel call, pulls specific financial/drug data from named sources, handles off-calendar fiscal years, sorts by primary metric, returns paired data with citation URIs, and replaces 8–15 lookups. No contradiction with annotations.

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

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

The description is dense but every sentence provides value: trigger phrases, explicit usage preference, data source details, edge cases, sorting, and output format. It is front-loaded with purpose. While on the longer side, it avoids redundancy and remains well-organized.

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

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

For a tool with 2 simple parameters and no output schema, the description covers practically all needed context: data sources, entity-specific behavior, sorting rule, output content (paired data + citation URIs), and performance benefit. The off-calendar fiscal year handling is particularly valuable. Nothing significant is missing.

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

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

Schema coverage is 100%, but the description goes further. It explains what each type ('company' vs 'drug') does with concrete data fields (10-K revenue, FAERS counts), gives examples for the values array (['AAPL','MSFT'], ['ozempic','mounjaro']), and clarifies constraints (2–5 items). This adds meaning beyond schema descriptions.

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

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

The description clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' — a specific verb and resource. It also lists trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') and distinguishes itself from sequential single-entity lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance and naming the alternative to avoid. It also implies when not to use (single-entity lookups) and provides context for both company and drug entity types.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes well beyond: it reveals the tool decomposes questions into facets, routes to 5,529 tools in parallel, returns gaps[] for unanswered facets and never invents answers, includes hop and citation_uri fields, has timing expectations (15-60s, up to ~90s for thorough), and explains the semantics of standard vs thorough. This is rich behavioral context that annotations do not 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 each clause earns its place; it front-loads the critical account requirement and sibling alternative, then explains core mechanics, then details the response format and timing. It's structured as a cohesive paragraph with clear topic progression, but one might argue it could be split into bullet points for easier scanning. Overall, it's compact for the amount of high-value context it provides.

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 carries the full burden of explaining return values—and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]. It also covers behavioral limits (structured catalog only), cost/account gate, latency, and multi-step resolution. For a complex 2-param tool, this is complete and leaves no significant operational question unanswered.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining how depth values behave: quick=3 facets, standard=5 with gap recovery, thorough=8 with full iterative hop. It also clarifies that the question parameter accepts broad/multi-part questions and that decomposition is the point, which goes beyond the schema's dry phrasing.

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

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

The description uses a specific verb ('research') with a clear resource ('Pipeworx's 1455 STRUCTURED data sources') and explicitly distinguishes from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups. It also names the sibling alternative, so it's not just clear but well differentiated.

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

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

The description gives explicit when-to-use ('best for broad/multi-part questions over structured data'), when-not-to-use ('for a single lookup use ask_pipeworx', 'for BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and names concrete alternatives. It also tells the user the account requirement and that ask_pipeworx works on every tier, making the decision path very clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context: returns top-N results, includes full input schemas with curated examples, and each result is 'ready to call directly, no second schema lookup needed'. This is information beyond annotations and helps set expectations.

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

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

The description is front-loaded with the core purpose and then expands into usage and return behavior. The long domain list is somewhat repetitive with schema examples but still serves as an illustrative guide. Each sentence earns its place, though it could be slightly tightened.

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

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

For a discovery tool with no output schema, the description adequately covers what results look like (top-N, names, descriptions, schemas). It also gives a clear 'call first' directive. The only minor gap is not explicitly noting that results are actual tools that can be called, but the 'ready to call directly' line covers that.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond listing example domains, which are also present in the schema examples. It does not explain the aliases or limit parameter, but the schema already does. Thus, no significant added value.

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

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

The description opens with a clear verb+resource pair ('Find tools') and immediately distinguishes itself as a meta-tool for discovering other tools. It lists specific data domains and explicitly contrasts with 'not just one answer', separating it from sibling tools that answer specific 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?

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. This clearly states when to use and implies when not to use (when you need a specific answer from a known tool).

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

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

Beyond the readOnly/idempotent annotations, the description discloses specific behaviors: parallel fan-out across sources, patent API sunset soft-fail, GDELT→GNews fallback, filing cap (up to 5), and output sorting. These are genuinely useful context for an agent.

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

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

The description is dense but front-loaded with examples and purpose. Some content repeats schema details (parameter examples, name restriction), but the extra caveats and return-value breakdown are valuable; a bit of trimming would make it 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?

With no output schema, the description enumerates all returned components (CIK, filings with URIs, fundamentals, patents, news, LEI), including failure modes and fallbacks. This gives an agent sufficient understanding of what the tool will do.

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

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

Schema already covers 100% of parameters with descriptions, including ticker/CIK examples and name restriction. The description adds little beyond repeating the same constraints, so baseline 3 is appropriate.

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

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

Description states it produces a 'full cross-source profile of a US public company in ONE parallel call', a specific verb+resource+scope. It distinguishes from sibling lookups by explicitly preferring over single-pack SEC/XBRL/news lookups and references resolve_entity for names.

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?

Gives explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when-not-to-use ('names not supported — use resolve_entity first'). This is clear and actionable.

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 destructiveHint and idempotentHint, and the description adds context about deleting stored memories by key and clearing sensitive data, without contradicting the annotations.

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

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

Two sentences, front-loaded with the action, 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?

Simple tool with one fully documented parameter, safety annotations, and clear usage intent; description covers what, when, and related tools, making it complete for an agent.

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

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

Schema description covers 100% of the parameter with 'Memory key to delete', so the description's mention of 'by key' adds no extra semantics 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?

Explicitly states the verb 'Delete' and the resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall which perform other memory operations.

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 usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and mentions pairing with remember and recall, giving clear context for when to invoke.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond annotations by describing the fetch/extract/emit process and the output as a standard llms.txt markdown blob. This goes beyond the baseline, though it doesn't cover edge cases like invalid URLs.

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

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

The description is two sentences, front-loads the core purpose and process, and follows with concrete use cases. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers the necessary context: the output format is explicitly stated, the placement (site-root/llms.txt) is mentioned, and use cases are listed. The annotations handle safety and idempotency, so the description is complete for practical selection and invocation.

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

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

The input schema provides 100% description coverage for both parameters (url and max_links), including defaults and format. The tool description does not add any extra parameter-level semantics beyond what the schema already states, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the process (fetches, extracts, emits) and the output format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on assessing AI presence rather than generating the file.

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

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

The 'Useful for' section lists specific scenarios (indexing a client's site, drafting for own project, auditing competitors), providing clear context on when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full exclusionary guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that by default only active subscriptions are listed. 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 extremely concise: two sentences that front-load the purpose and return fields, then give concrete usage guidance. Every sentence earns its place without redundancy or unnecessary elaboration.

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 list tool with one optional parameter, the description is complete: it states the purpose, return format, default behavior (active only), and specific use cases. The sibling tools (subscribe/unsubscribe) make the context clear, and the annotations cover safety semantics, so the description fills the remaining gap effectively.

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

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

Schema description coverage is 100% for the only parameter include_inactive, with a clear description already in the schema. The tool description adds no additional semantic detail about this parameter beyond the schema, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('List') with a clear resource ('the caller's active subscriptions') and enumerates the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by explicitly focusing on reviewing active subscriptions and finding IDs to cancel.

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 tells the user when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when not to use it (e.g., for subscribing or unsubscribing) and names the alternative actions, making the usage context clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds some context by listing example stats (sync status, version, latest block) but does not disclose error behavior, permission requirements, or the return format beyond what the output schema would provide. This is an acceptable but not rich disclosure.

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

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

The description is a single, concise sentence fragment that is front-loaded with the key term 'Node software stats'. Every word adds value, and the ellipsis effectively signals that more examples exist without wasting space. It is appropriately sized for a simple tool.

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

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

For a low-complexity tool with one parameter, an output schema, and strong annotations, the description is minimally acceptable. It names the resource and gives examples of the data returned. However, it lacks usage guidance and parameter semantics, which are clear gaps given that the schema provides no descriptions. The annotations and output schema compensate for some of the missing context.

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

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

The schema has 0% description coverage for the 'chain' parameter, and the description does not mention or explain the parameter at all. The only hints are the examples in the schema showing 'bitcoin' and 'ethereum', which imply the parameter is a blockchain identifier. The description fails to compensate for the missing parameter documentation, leaving the agent to infer semantics from the examples.

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

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

The description 'Node software stats (sync status, version, latest block, …)' clearly identifies the tool as retrieving node-level statistics for a blockchain node. It specifies the resource (node software) and the type of data (sync status, version, latest block), distinguishing it from sibling tools like 'block' or 'transaction'. However, it lacks an explicit verb like 'get' or 'retrieve', which keeps it from being a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any specific use case, exclusions, or context where another tool would be preferred. With siblings like 'stats' and 'block', the absence of usage direction leaves the agent to infer applicability from the name and short description alone.

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

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

Annotations are all false, providing no safety or idempotency info. The description compensates by disclosing rate limits ('5 per identifier per day'), the claim_token workflow, that reports are read daily, and that the tool is free and quota-free. This is rich behavioral context beyond structured fields.

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

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

Compact but dense; every sentence conveys a distinct point (purpose, when-to-use, exclusions, token flow, limitations). It is longer than a one-liner but well-structured with the opening sentence carrying the core purpose.

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

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

No output schema exists, so the description is the only source for understanding the response/claim_token flow. It covers scope boundaries, error categories, submission format, rate limits, and follow-up usage. This is complete for a feedback tool with nested optional context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds constraints not in the schema: claim_token must be passed alone ('with no other arguments') and message should be specific, 1-2 sentences. It also advises describing issues in terms of Pipeworx tools/packs, which clarifies the `context` object's intent.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and explicitly enumerates feedback types (bug, feature/data_gap, praise). It distinguishes from sibling tools like ask_pipeworx by framing this as feedback about Pipeworx's own tools, not a question.

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: 'Use when a tool returns wrong/stale data...', when a tool is missing, or praise. Includes clear exclusions: 'ONLY for tools served by this Pipeworx connection' and instructs to file external-tool issues elsewhere. Also warns against pasting end-user prompts.

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

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

Annotations already declare readOnly/openWorld/idempotent. Description adds non-obvious behaviors: sourced from CF analytics-engine, no PII, caching 5min-1h, and return shape (pack, tool, count).

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

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

Three sentences, each earning its place: purpose, use cases, then aggregation/caching details. Front-loaded with the core function, 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?

No output schema, yet description explains return contents and data shape. Also covers caching and aggregation provenance. Complete for a read-only aggregation 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?

Input schema covers window param 100% with enum and per-window semantics. Description only restates the window options without adding new parameter 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 uses specific verb 'Returns' with resources: top tools, top packs, total call volume. Opens with 'What other AI agents are calling on Pipeworx right now', giving an immediately clear purpose that distinguishes it from sibling 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?

Lists three explicit use cases: discovering hot data sources, confirming a canonical tool, and assessing alignment. Provides situational context but doesn't name alternatives or state when-not-to-use.

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

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

Recognizing the annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral detail: the no-args scan, the partition_check's 3pp threshold, the placeholder filter, and the crucial fill check caveat that realizable_edge_pp ≤ 0 means the edge is not tradable. This goes far beyond the annotation baseline.

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?

Despite being long, the description uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK, Response) and front-loads the core purpose and mode distinction. Every sentence contributes unique information: response shape, edge-case behavior, and tool-specific limitations. No filler or tautology.

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

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

Since there is no output schema, the description must explain return values, and it does: opportunities[] with fields, partition_check structure, and the fill check behavior. It covers no-arg usage, both modes, failures (skipped_low_similarity, null arb), and how to follow up with a sibling tool, making it complete for a complex data analysis 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?

While the schema already documents both parameters, the description dramatically expands their meaning: it explains what "event" expects (Polymarket event slug or URL), what "topic" expects (seed question), and how each mode behaves. This is not redundant with the schema—it adds operational context that is essential for 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 opens with a specific verb and resource: "Find arbitrage opportunities on Polymarket". It clearly distinguishes from sibling tools by naming the mechanism (monotonicity violations + partition-sum checks) and by referencing alternatives like polymarket_fill_risk for custom sizing. The two modes (event vs topic) further clarify the tool's scope.

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

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

Explicitly states when to use each mode: "event (recommended for a specific market)" and "topic (for cross-event scanning)", and even explains the no-arg default `trending_scan`. It provides concrete examples (event slugs, topic seeds) and points to a sibling tool for a different use case, giving clear when/when-not guidance.

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

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

Beyond the read-only/idempotent annotations, the description reveals extensive behavioral details: caching (1h at KV level keyed on all knobs), response structure (by_segment, fed_candidates, _diagnostics), edge calculations (edge_pp_net after slippage, Kelly caps), and filtering rules (placeholder-slug drop, >20% placeholder fraction skip). It also flags limitations such as the unreliable 1m-T vs EFFR signal without paid data.

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 dense, single-paragraph wall of text that covers enormous ground. While every sentence earns its place for a complex tool, the lack of structure (no bullet points or headers) makes it harder for an agent to parse. It is front-loaded with the core purpose but quickly becomes technical.

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

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

Without an output schema, the description fully specifies the response envelope: top-level by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also details the per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume) and the 24h-move warning.

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 explaining parameter interactions: min_partition_leg_kelly is the per-leg counterpart to min_kelly for partition arbs because parent kelly_fraction_half is always 0; min_liquidity/max_spread_pp act as tradeable-edge filters. These semantic clarifications go beyond the schema's field descriptions.

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

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

The description opens with a specific verb-resource-purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates itself from sibling tools by focusing on Pipeworx-driven signals across three model segments.

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

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

It states when to use: 'Built for "what should I bet on today" – agents discover opportunities without paging hundreds of markets.' It also provides when-not guidance, excluding Fed bets as unreliable and dropping placeholder-slug backstops. However, it doesn't explicitly name alternatives among sibling tools, so it's not a full 5.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds substantial behavioral detail: return structure (tracked/expired/snapshot_dates), data caveats (snapshot misses, TTL limits, decay computed from daily closes not intraday), and the signed meaning of edge_pp_net. 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 long but well-structured with Args, RESPONSE, and LIMITS sections. Every sentence provides substantive information, especially since there's no output schema. It front-loads the core purpose before diving into details, making it easy to scan.

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

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

Given no output schema, the description excellently explains the return shape (tracked[] with fields, expired[] with lifespan_days, snapshot_dates[]) and critical caveats (snapshot TTL, gaps, daily closes). It covers not only return values but also the data source quirks, making it complete for the tool's complexity.

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

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

The input schema already describes both `days` and `window` with 100% coverage, so baseline is 3. The description's args line adds minimal extra context (e.g., 'snapshot family' for window), but mostly restates defaults and bounds already present in the schema. It does not add significant format details beyond what the schema provides.

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

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

The description opens with a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from raw edge computation by referencing the sibling `polymarket_edges` tool, indicating this is a complementary analysis tool.

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

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

The description provides clear context for when to use the tool: to analyze edge history and decay, contrasting fresh vs stale edges. It does not explicitly name alternatives or state when not to use it, but the use case is concretely framed ('fresh wide edge vs 3-week-old wide edge are different trades') and the response structure is outlined, aiding selection.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint, idempotentHint, non-destructive). It details the execution path: walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict. It also warns about thin_legs and forced_directional_risk, which are non-obvious behaviors. No contradictions with the annotations are present.

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, front-loaded with the core purpose and then organized by mode (SINGLE-MARKET vs BASKET). Every sentence adds relevant detail—parameters, return values, usage context, and failure modes. It is not overly verbose for the complexity of the tool, though it could be tightened without losing essential 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 absence of an output schema, the description thoroughly enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers parameter dependencies (market vs event), defaults, size interpretation, and the risk rationale. For a tool with 4 parameters and no output schema, this is 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying nuanced semantics for size_usd: 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains the default and auto-detection behavior for side in basket mode. This is helpful, though the schema already describes each parameter clearly.

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

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

The description opens with a specific verb+resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines two operating modes (single-market and basket) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by naming them and specifying its role as a pre-trade check. This goes beyond a generic one-liner.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, noting that theoretical overround is not capturable on thin books and partial basket fills create unhedged directional positions. This gives the agent clear when-to-use and when-not-to-use context relative to alternatives.

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

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

Despite strong annotations (readOnly, idempotent, not destructive), the description adds rich behavioral detail: compatibility_warning logic, temporal_alignment, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics often lack equivalent bet shapes. 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?

Long but well-structured with labels (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence carries essential information, though it could be slightly tightened.

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

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

No output schema, so the description must document return values; it does so by listing leg-by-leg prices, top_spreads_pp, compatibility_warning cases, temporal alignment, and skipped counters. Covers edge cases thoroughly.

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

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

The description explains how topic vs explicit parameters interact, lists all valid topic shortcuts, and states that explicit parameters override defaults. Schema already has 100% coverage, but the description adds meaning beyond field descriptions.

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

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

Clearly identifies the tool's function: cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes and response details. It distinguishes from sibling Polymarket-only tools by explicitly naming both venues and the matching logic.

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 two modes (topic shortcuts vs explicit ticker/slug) and warns that most pre-mapped topics return compatibility warnings, indicating when results may not be meaningful. Does not explicitly name alternative tools, but the 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?

Annotations already mark the tool as read-only and idempotent; the description adds the key behavioral trait of scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all saved keys when the key is omitted, enriching the agent's understanding beyond the safety hints.

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

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

Two sentences pack the core operation, usage context, scoping, and related tools without redundancy. Every clause earns its place and the description is front-loaded with the main action.

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

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

For a simple 1-optional-parameter read tool with adequate annotations and no output schema, the description fully covers behavior, scoping, and relationships to remember/forget. There are no missing pieces.

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

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

The schema already fully documents the optional 'key' parameter with a description matching the tool's behavior, so schema coverage is 100%; the description adds example key values ('user's target ticker, an address, prior research notes') which gives semantic context but doesn't change the parameter's meaning. Baseline 3 is appropriate.

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

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

The description opens with a precise verb phrase: 'Retrieve a value previously saved via remember, or list all saved keys,' clearly distinguishing the read operation from the sibling 'remember' (save) and 'forget' (delete) tools. It also explicitly states the two modes of operation, making the tool's 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?

It explicitly instructs when to use: 'Use to look up context the agent stored earlier ... without re-deriving it from scratch,' and names the paired tools 'remember' and 'forget,' which clarifies the workflow and alternatives. It also describes scoping to the user's identifier, providing additional 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?

The description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the annotation readOnlyHint:true. The annotation claims the tool is read-only, but the description reveals a write operation, making the behavior misleading.

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

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

The description is a single paragraph of about four sentences, each earning its place: it states purpose, return fields, filtering options, mark_read behavior, polling note, and alternative endpoint. No wasted words, and it leads with the core action.

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

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

With 5 parameters and no output schema, the description covers return format (source, citation_uri, payload), filtering, mark_read semantics, polling suitability, and an HTTP alternative. It does not explicitly explain unread_only or limit defaults, but these are in the schema. The contradiction with readOnlyHint slightly undermines completeness, so not a 5.

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%, providing baseline 3. The description adds meaningful semantics beyond the schema by giving an example for type ('sec_8k'), clarifying the since format (ISO timestamp), and explaining the effect of mark_read (only newer events on next call). This extra context justifies a 4.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly explains the tool returns recent alerts with their source, citation_uri, and raw payload, distinguishing it from siblings like recent_changes or list_subscriptions by focusing on alerts and the persisted feed.

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

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

It gives a clear usage context: polling works fine, filtering by type and since, and using mark_read/unread_only. However, it does not explicitly name when to use this tool over siblings, only mentions an alternative HTTP endpoint. This is clear context without exclusions, so a 4 is appropriate.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavioral context: multi-source fan-out, fallback behavior, USPTO soft-fail due to API sunset, and parallel execution. This goes well beyond annotations, disclosing important runtime behaviors and edge cases.

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

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

The description is dense and information-rich, front-loaded with user-facing examples. While every sentence provides useful info, the opening contains six synonymous phrasings of the same query pattern, which is slightly redundant. Overall, it is well-structured and each sentence contributes, but it could be tightened.

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

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

Given the tool's complexity (three data sources, fallbacks, no output schema), the description fully explains return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), parameter behavior, source-specific quirks, and the alternative tool. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the schema already contains the full parameter documentation including ISO/relative formats for 'since' and ticker/CIK for 'value'. The description repeats these details, adding only a minor recommendation ('Use 30d or 1m'). As per the baseline rule for high coverage, a 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 immediately provides natural language queries and states the core function: 'change feed for a company in the last N days/weeks/months'. It clearly identifies the verb (get change feed) and resource (company), and differentiates from the sibling entity_profile by mentioning its alternative. This is as clear as the TDQS 4.3 example.

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 tells when to use this tool vs. alternatives: 'Use entity_profile instead when you want the static profile... regardless of window.' It also provides context on when the fallback sources activate (GDELT→GNews on rate-limit/5xx), which helps the agent decide. This meets the explicit-alternative and when-not-to-use criteria.

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

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

The description adds behavioral context beyond the annotations: persistence differences for authenticated vs. anonymous sessions, scoping by identifier, and the key-value storage model. While annotations already indicate idempotent and non-destructive behavior, the description clarifies the memory retention policy.

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 about 80 words and well-structured. It front-loads the main purpose, then gives usage context, storage details, and a pointer to related tools. Every sentence adds value with no redundancy.

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

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

For a simple write tool, the description is complete: it covers what to store, when to use it, how data is persisted, and how it relates to recall and forget. The lack of an output schema is acceptable since this is a write operation, and the schema already documents both required parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the key-value model and notes that 'value' can be any text, but it does not add substantial meaning beyond the schema's descriptions of 'key' and 'value' parameters.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later' as a key-value pair. It distinguishes itself from siblings by explicitly mentioning paired tools (recall, forget) and giving concrete examples of what to store.

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

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

The description provides explicit 'when to use' guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names complementary tools (recall, forget) for retrieval and deletion, though it does not explicitly state when not to use the tool.

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

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

The description adds significant behavioral context beyond the annotations. It discloses graceful degradation ('LEI/FIGI enrichment degrades gracefully...'), explicit unresolved identifier handling ('stated explicitly under `unresolved` rather than omitted'), and internal cascading lookups ('Each call cascades through several lookup endpoints internally'). These details go well beyond the read-only/idempotent hints and help the agent set expectations.

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

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

The description is dense but well-organized. It front-loads with user-like queries, then gives a direct usage directive, and follows with structured entity type explanations. Every sentence adds value, though the length is above average. The lack of fluff and the clear thematic sections earn it a strong 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?

With no output schema, the description carries the burden of explaining return values. It covers the key outputs for both entity types, the 'unresolved' field behavior, and resilience under partial data source availability. It also explains the tool's internal operation and benefit. It could be more explicit about the exact output structure or format, but the level of detail is sufficient for an agent to make informed decisions.

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

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

The schema already covers both parameters with descriptions and enum values, giving 100% coverage. The description adds complementary semantics by explaining what each entity type returns (e.g., company yields CIK, ticker, LEI, FIGI; drug yields RxCUI, ingredient, brand) and elaborates on accepted input formats (ticker, CIK, name; brand or generic). This enhances the parameter 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 the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes specific examples ('What's the ticker for...', 'find the CIK for...') and explicitly distinguishes it as the go-to tool when you have a name but need an ID ('Use FIRST whenever you have a name but need an ID'). This differentiates it from siblings like entity_profile or compare_entities.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to invoke this tool. It also explains that it replaces '2-3 manual lookups,' suggesting efficiency. However, it doesn't explicitly mention when not to use it or name alternative tools, so it falls short of full usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it performs N+1 probes, calls ai_visibility_check internally, ranks results, and returns score/confidence/signal density. It also notes that _apiKey is passed to api.anthropic.com per probe, covering auth behavior succinctly.

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

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

The description is concise and well-structured: purpose first, then mechanics, then use case, then output details. Every sentence adds value with no filler, and the front-loading makes the tool's core function immediately clear.

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

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

For a tool with 4 parameters and no output schema, the description covers input semantics (entities, models, context, API key), output format (ranked list with score/confidence/density), use case, and the relationship to ai_visibility_check. This is fully complete for an agent to select and invoke correctly.

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

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

Schema descriptions cover 100% of parameters, earning baseline 3. The description adds meaning beyond the schema by explaining that the first entity is treated as the 'subject' for narrative and the rest are competitors, and clarifies the shared 'context' disambiguates names. This extra context justifies a 4.

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

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

The description uses a specific verb ('Compare AI visibility') and resource ('multiple entities side-by-side'), clearly distinguishing it from the sibling ai_visibility_check (single entity) and compare_entities. It also states the ranking/recognition outcome, making the tool's function unmistakable.

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

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

Provides a clear use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). It implicitly contrasts with ai_visibility_check by saying it probes each entity with that tool, but does not explicitly state when not to use it or name alternative tools like compare_entities.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses key behavioral traits: it fans out to multiple sources, handles partial failures gracefully, notes that bundlephobia's first measurement can take 5-30s, and explains that sources_failed will list timeouts. This adds substantial context not available in annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then logically covering usage, return values, ecosystem scope, and error handling. Every sentence contributes unique value with no fluff or repetition.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers return values (summary block fields, per-advisory detail, links, alternative versions), error handling, and performance caveats. This is sufficient for an agent to understand what to expect and how to handle 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?

The schema already provides 100% coverage of both parameters (package and version) with clear descriptions, including scoped packages and default behavior. The description does not add additional semantic meaning beyond restating the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, listing specific data sources (deps.dev, bundlephobia) and the types of information gathered. It distinguishes itself from siblings by focusing solely on npm dependency scanning, with no overlap.

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

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

Explicitly states when to use it: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusion guidance, noting the NPM ecosystem only in v1 and directing other ecosystems to deps.dev:version directly.

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

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

The description discloses embedding details (BGE-base-en, cosine), window size (500-char), input cap (200K) with truncation flag, and return structure (offsets, similarity scores), all beyond the existing read-only annotations.

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

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

Three dense sentences: purpose, usage, and implementation. Front-loaded with the core verb and resource; every sentence adds information without waste.

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

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

The description fully covers the tool's complexity: no output schema, but it specifies return values, truncation behavior, and usage guidance, making it self-contained.

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

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

Schema description coverage is 100%, but the description adds practical context with examples for text and query, and explains the offset/score in the result, enhancing the 'limit' 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 opens with 'Semantic search INSIDE a fetched record,' clearly stating the action and target. It distinguishes from siblings by emphasizing 'INSIDE a fetched record' and explicitly referencing ask_pipeworx_grounded as a companion.

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

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

It provides explicit usage conditions: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded,' offering an alternative/companion and clarifying when to prefer this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'chain-wide' aggregation scope and the list of statistic types, but does not disclose additional behaviors like rate limits or caching. This is acceptable given annotation coverage, but not exceptional.

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

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

A single, front-loaded sentence that efficiently communicates the tool's purpose, parameter semantics, and supported chains 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?

For a simple read-only tool with one parameter and an existing output schema, this description covers purpose, parameter meaning, and usage context. No significant gaps are apparent; the output schema handles return value details.

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 provides only the type 'string' for chain with no description or enum. The description adds meaning by stating the parameter represents a blockchain (bitcoin, ethereum, dogecoin, and 12 others), giving concrete examples and clarifying the parameter's role in the tool. This compensates for the 0% schema coverage, though it doesn't enumerate all valid values.

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 the specific verb 'Fetch' and identifies the resource as 'chain-wide blockchain statistics' with concrete examples (block count, transaction volume, hash rate, mempool size, circulation), clearly distinguishing it from sibling tools like block, transaction, or address that target specific entities.

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

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

The description clearly implies usage when chain-wide aggregate statistics are needed, and the chain parameter context is explicit. However, it does not explicitly state when not to use this tool or mention alternatives, so it falls short of full explicit 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?

Despite annotations already conveying non-read-only and idempotent behavior, the description adds substantial operational details: account requirements, phone verification, SMS daily cap, webhook auto-disable after 10 failures, and one-time return of the webhook signing secret. This goes beyond the annotations and helps the agent manage side effects.

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

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

The description is front-loaded with purpose and return value, and every sentence contributes operational knowledge. However, it is a dense wall of text with many parentheticals; splitting into bullets or paragraphs for types and delivery channels would improve scannability without adding 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 (three parameters, nested objects, multiple types, multiple delivery channels, no output schema), the description covers the return value, prerequisites, type-specific semantics, delivery behaviors, and limitations. It only lacks explanations for patent_grant and clinical_trial, but those are partially addressed in the input 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 description coverage is 100%, so baseline is 3. The description enhances meaning for three of the five subscription types (sec_8k, polymarket_edge, fred_series) by explaining what they monitor, but it omits patent_grant and clinical_trial. It also adds practical delivery constraints (E.164, verified phone) that complement the schema.

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

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

The description opens with a specific verb+resource: "Create a proactive monitoring subscription to a live-data event stream" and promises the subscription id as return value. This clearly distincts from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Explicitly states the prerequisite (Pipeworx OAuth account, anonymous/BYO cannot persist), provides alternatives to subscribing (pull via recent_alerts or GET registry.pipeworx.io/alerts.json), and enumerates supported subscription types with concrete examples. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral context by noting the content is drawn from a live catalog and that it returns tool+argument shapes, which goes beyond the annotations without contradicting them.

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

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

The description is somewhat lengthy but well-structured, starting with user-facing query phrases, then explaining returns, then usage instructions. Every sentence contributes essential information, and while it could be tighter, it remains efficient for the tool's complexity.

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

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

For a tool with one optional parameter and no output schema, the description is exceptionally complete. It covers when to use it, how to call it (with and without arguments), what it returns, and provides examples, leaving no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents the topic parameter. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a full spread, enriching the semantic understanding beyond the schema's generic description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool and argument shapes, positioning itself as the onboarding entry point. It provides example queries ('what can I ask Pipeworx?') and distinguishes itself from siblings by being the 'FIRST' tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments or with a topic. It does not explicitly name alternatives, but it clearly indicates when this tool is most appropriate, satisfying the 'when to use' requirement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond the schema fields—it does not disclose return format, error behavior, or any subtleties. It essentially restates what the tool name implies.

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, short sentence with no wasted words. It is front-loaded with the key concept. However, it is under-specified, which slightly reduces the score from a perfect 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?

The tool is simple with only two parameters and an output schema, so the description does not need to explain return values. But it fails to mention the required 'chain' parameter, which chains are supported, or how this differs from related tools. The existing annotations and output schema mitigate some gaps, but the description remains incomplete for reliable invocation.

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

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

Schema description coverage is 0%, so the description must explain parameters, but it only mentions 'by txid' and completely ignores the required 'chain' parameter. The schema examples hint at possible chains (bitcoin, ethereum) but no description is given, leaving the agent to infer meaning from examples alone.

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

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

The description 'Transaction details by txid.' clearly identifies the resource (transaction) and the lookup key (txid), distinguishing it from siblings like 'block' or 'node'. However, it lacks an explicit verb like 'get' or 'retrieve', and it omits the 'chain' parameter, which is necessary context.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'block' or 'address'. It does not mention any prerequisites, exclusions, or scenarios where the tool is appropriate. This leaves the agent without direction for tool selection.

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

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

Beyond the annotations, the description adds important side-effects: the row is deactivated (not deleted) and historical events remain available via recent_alerts. Ownership enforcement is also disclosed. This aligns with destructiveHint: false and enriches the behavioral model.

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

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

Two sentences, front-loaded with the action, then constraints and side-effects. Every sentence earns its place with zero 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?

The description covers the core action, ownership constraints, and the deactivation side-effect. Combined with the annotations (idempotent, not destructive, not read-only), the tool is fully described for a simple single-parameter 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?

The schema already fully describes the single parameter 'id' with 100% coverage. The description adds minimal extra meaning, only restating that cancellation is by id, which is already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes itself from siblings like subscribe (creates) and list_subscriptions (lists), and the id-based targeting is precise.

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

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

It provides clear context that ownership is enforced, so users know they can only cancel their own subscriptions. However, it doesn't explicitly mention alternatives or when-not-to-use scenarios, though the name and sibling context make the primary use obvious.

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

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

Beyond the read-only, open-world, idempotent annotations, the description adds rich behavioral detail: the verdict enum, the meaning of 'could_not_verify' (failure, not evidence), the difference between 'unsupported' and 'could_not_verify', the fallback pipeline, and the citation format. This significantly exceeds what the annotations provide and is not contradictory.

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 thoroughly organized, front-loading natural-language triggers and then covering purpose, routing, verdicts, and important caller warnings. The 'IMPORTANT for callers' section and explicit verdict list justify the length, though the repeated trigger phrases could be tightened. It is concise for the amount of critical detail conveyed.

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

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

Since there is no output schema, the description fully explains return values, verdict semantics, error handling (verification_error), and unsupported cases. It also explains the tool's composite nature (replacing 4-6 calls) and covers routing decisions. This makes it complete for a complex tool with no structured output definition.

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

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

Schema description coverage is 100%, with both 'claim' and 'tolerance_pct' already documented in the input schema. The description does not add parameter-specific nuance beyond the schema; it only references tolerance indirectly via 'exact percent-delta math'. Thus the baseline of 3 applies.

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

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

The description explicitly identifies the tool as a natural-language claim verifier with trigger phrases like 'fact check' and 'verify the claim that…'. It also lists the specific verdicts returned and distinguishes itself from generic Q&A tools by framing it as a replacement for a multi-step pipeline, and by splitting claims into financial vs. other categories. This is specific and differentiates it from siblings.

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

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

It clearly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing context for financial vs. non-financial claims. However, it does not explicitly name alternative tools or state when not to use it, so a 4 rather than 5.

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