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 declare the tool read-only, open-world, and idempotent, and the description adds meaningful behavioral detail: it routes across a large toolset, auto-fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradiction exists between the description and 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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and packs in usage rules, examples, and escalation paths. Some redundancy exists in the extensive domain enumeration, but most sentences carry useful routing 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 simple schema of a single question string and no output schema, the description fully covers what the tool does, when to use it, when to step up to alternatives, what outputs to expect, and example query formats. An agent has enough context to call it correctly in the default case.

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

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

Schema coverage is 100% and all six parameters are aliases of the single `question` string, so the schema fully documents the parameters. The description offers natural-language guidance and examples but does not add new parameter-level semantics beyond what the schema provides.

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

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

The description clearly states the tool routes a natural-language question to one of 5,743 tools across 1,500 verified sources, fills arguments, and returns a structured answer with citation URIs. It distinguishes itself from ask_pipeworx_grounded and deep_research by naming them explicitly.

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 factual questions about real-world entities, events, or numbers. It also names alternatives for edge cases — ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions — and provides concrete example queries.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, lowering the bar for the description. The description adds meaningful context beyond annotations: it is a live experimental edge, candidate improvements can be active, it currently matches ask_pipeworx exactly, and it is a fully working router with no fallback. This gives the agent a clear behavioral model 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?

The description is moderately detailed but each sentence earns its place: it defines the tool, states the current active-candidate status, gives usage direction, and reassures that it is fully functional. Some repetition exists ('identical universal router' and 'same 5,743 tools, same arguments, same response shape'), but it is not excessive.

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

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

For a single-question universal router with no output schema, the description provides everything needed to invoke it correctly: what it does, how it relates to ask_pipeworx, when to use it, its current experimental state, and its non-fallback behavior. The response shape is explicitly stated to match ask_pipeworx, so the missing output schema is not a gap.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases of the single 'question' parameter, so the schema already carries the semantic burden. The description adds no parameter-specific detail beyond saying the arguments are the same as ask_pipeworx, which is sufficient given the high coverage.

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

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

The description states a specific purpose: it is the beta version of ask_pipeworx, a universal router over the same 5,743 tools with the same arguments and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling by its experimental routing status, so an agent can tell it apart.

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 to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies the current state ('No candidate is active right now'), so the agent knows when this tool matches the stable version exactly and when it may differ.

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 mark it read-only, open-world, idempotent, and non-destructive; the description goes well beyond this by disclosing the refusal behavior, the exact refusal_reason enums, evidence quoting, and the constraint that it extracts only from tool results. It does not contradict any annotation.

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

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

The description is information-dense and front-loaded with the core differentiator. Each sentence adds value, including return shapes and refusal reasons; however, it is a long single paragraph and could be slightly better structured with separation of concerns. Still, no filler exists.

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 high complexity (routing across 5,743 tools), the simple one-parameter schema, and the absence of an output schema, the description is complete: it covers success and refusal return shapes, use cases, cost tradeoff, and the alternative tool. Nothing an agent needs to call or decide on this tool correctly 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 description coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no new parameter-level meaning, but the schema already fully covers the single semantic input. 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?

States a specific mode ('Hallucination-resistant answer mode'), describes the underlying routing ('Same routing as ask_pipeworx'), and clearly differentiates itself by adding extraction-only grounding. The agent can immediately distinguish this from ask_pipeworx and ask_pipeworx_beta.

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

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

Explicitly says when to use it: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is 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?

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 readOnly, openWorld, and idempotent hints, and the description adds substantial non-obvious behavior: account/tier requirements, parallel decomposition across 5,743 tools, gaps[] never invented, contradictions[], fetchable pipeworx:// citations, semantic excerpting, and 15-90s latency. The description does not contradict any annotation.

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

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

The description is long but appropriately so for a complex tool; every sentence carries a distinct operational fact a caller needs: prerequisite, scope, alternatives, depth semantics, return packet shape, citation fetchability, and latency. The critical account gate is front-loaded before the research details.

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

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

With no output schema, the description fully covers what an agent needs to call the tool correctly and interpret results: input semantics, expected findings packet, gaps[], contradictions[], citations, latency, and depth-dependent behavior. It even addresses the failure mode of off-catalog topics returning empty 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 100%, so the baseline is 3, but the description adds real incremental meaning by explaining the behavioral consequences of depth levels (gap recovery, lead chasing, contradiction scan) and clarifying that the question parameter supports broad/multi-part natural language. This goes beyond what the schema alone conveys.

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?

States a specific verb and resource: 'grounded multi-source research' across Pipeworx's 1,500 structured data sources in one call. It explicitly contrasts itself with open-web search and names ask_pipeworx as the alternative for single lookups, making sibling differentiation clear without requiring schema inspection.

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 ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use guidance (single lookups, breaking/current news topics), naming ask_pipeworx as the alternative. It also states the account prerequisite and instructs unsigned-in users to use ask_pipeworx instead.

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?

Annotations already cover safety (read-only, idempotent, non-destructive), and the description adds substantial behavior beyond that: parallel fan-out across external sources, soft-fail on USPTO, expected-empty FDA sections, sources_used/sources_failed, and private-company resolved:false behavior. It even prevents misinterpretations of empty data. No contradiction with annotations.

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

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

The description is long, but the length is earned by the tool's breadth: examples, source fan-out, return fields, caveats, and input modes. It front-loads the core behavior and preference rule before diving into detail. A few example strings and the final parameter note are redundant with the schema, keeping it just shy of 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?

Given there is no output schema, the description compensates by enumerating every return bucket (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed) plus edge-case behavior. For a high-complexity tool, nothing essential an agent needs to confidently invoke it is missing.

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

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

The input schema covers both parameters at 100% and already documents ticker/CIK/name inputs and type interchangeability. The description repeats essentially the same parameter semantics, adding only output-context notes like resolved_from/resolved_to. Since the schema carries the full parameter documentation burden, the baseline 3 is appropriate.

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

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

The description opens with concrete example queries and immediately defines the operation: a single parallel call that returns a full cross-source profile of a US public company. It explicitly contrasts itself with chaining single-pack lookups, so an agent can tell it apart from narrower research tools. The enumeration of return sections and accepted identifiers makes the tool's scope unmistakable.

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

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

It states an explicit preference rule: ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also gives behavioral guidance around private companies, name resolution, and expected-empty sections. It lacks a formal 'don't use for X' list, but the main selection context is clearly established.

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?

Beyond the read-only/idempotent annotations, the description discloses substantial dynamic behavior: keyword-based pairing with no shared resolution source (pairing_unverified), gross-vs-net spread due to unmodeled Kalshi fees, compatibility codes that can be non-empty even when pairs exist, skipped/unclassified legs, and temporal alignment caveats. It also sets realistic expectations that most pre-mapped topics currently return compatibility warnings. Nothing contradicts the annotations.

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

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

The description is long, but it is front-loaded with purpose, then modes, then response, then safety fields, using labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' to organize dense content. Almost every sentence earns its place given the tool's complexity and the absence of an output schema, though it could be tightened in places.

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

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

With no output schema, the description fully compensates by defining the response structure, safety codes, skipped counters, temporal_alignment semantics, fees_note, and edge cases such as unclassified legs and alignment_unknown. It gives an agent essentially a complete calling contract, including what null means and what to inspect before treating a spread as meaningful.

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

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

Even though the schema already covers all three parameters, the description adds interaction and override semantics: topic is a pre-mapped shortcut, the ticker/slug pair enables custom pairings, and both modes run the identical token-overlap matcher. It also clarifies which parameters override which mapped side, going well beyond the schema's property descriptions.

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

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

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — a specific data product with a clear verb and resource. It further defines two input modes and the response shape, making the tool unambiguous and distinguishable from venue-internal siblings like polymarket_edges or polymarket_arbitrage.

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

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

The description explains when to use topic shortcuts vs explicit ticker/slug pairings and warns that pre-mapped topics are not necessarily tradeable. However, it never names alternative sibling tools or gives explicit when-not routing (e.g., 'for X use polymarket_arbitrage instead'), so the cross-tool usage guidance is only implied rather than stated.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds substantial behavioral context beyond that: it explains cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, handling of ambiguous matches (returns figi_candidates), explicit labeling of unresolved identifiers, and how ISINs resolve to legal entities. This exceeds what annotations convey and fully informs the agent of 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 long but densely informative; every sentence contributes functional detail. It is front-loaded with usage examples and the 'Use FIRST' directive. The structured layout with 'SUPPORTED TYPES' and sub-bullets aids scanning. It is not excessively verbose given the complexity, but slightly tighter organization could earn 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 must explain return values and behavior, and it does thoroughly: it mentions figi_candidates for ambiguous matches, the unresolved array, source-labeled identifiers, and graceful degradation. It covers input handling, edge cases, and internal cascading, leaving nothing essential for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds critical semantic guidance not in the schema: for 'value', it clarifies that for bonds the issuer must be passed exactly as printed and warns against including security-class words (e.g., 'revenue bonds'). It also explains the input formats (ticker, CIK, ISIN, name) and how they resolve differently. This goes well beyond the schema's generic descriptions.

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

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

The description states a clear purpose: resolving a user-spoken name to canonical/official identifiers required by other tools. It provides multiple example queries and lists supported entity types (company, drug) with specific identifier details. It clearly distinguishes itself from sibling tools like entity_profile and compare_entities by focusing on name-to-ID resolution.

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 FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups, giving clear guidance on when to invoke it. It does not explicitly name alternative tools or exclusion conditions, but the 'FIRST' directive and the context of siblings strongly imply it is the primary resolver. A slightly stronger exclusion note would push this to 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. 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.