Urlhaus

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

Annotations already declare safe read-only, idempotent behavior. The description adds important details: default model, cost implications (free vs. BYO), and return structure (per-model score, confidence, etc.), which go beyond annotations.

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

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

The description is two sentences long, front-loads the main action, and every sentence adds value—no wasted words. Structured with clear information hierarchy.

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 purpose, usage, parameters, and return format adequately. It could mention limits (e.g., rate limits) but is sufficient for correct 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 100%, so the baseline is 3. The description adds extra meaning: explains default model behavior, usage of '_apiKey' as pass-through, and return structure details, providing clear value beyond the schema.

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

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

The description specifies a clear verb ('probe'), resource ('LLMs'), and scope ('what they know about a business/brand/product/topic'), and distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on specific entity visibility scoring.

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

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

The description states when to use (AI-marketing audits, brand checks) and provides conditional guidance (e.g., needing '_apiKey' for Anthropic). While it does not explicitly exclude alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond those flags: it routes among 5,706 tools across 1,493 sources, returns stable pipeworx:// citation URIs, makes one fast call, and works on every tier. No contradiction exists.

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

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

The description is front-loaded with the key directive and packs in examples, domain coverage, and alternatives without fluff. It is long but each section earns its place; minor repetition such as 'START HERE' reinforcing 'PREFER' is acceptable.

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

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

There is no output schema, but the description explains the return form (structured answer with stable citation URIs), the input style, the tool's default status, and when to switch to siblings. Error behavior and failure modes are not described, but for a read-only factual lookup tool this is adequate.

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

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

The schema already documents all six parameters with 100% coverage, including the alias relationship between question and q/text/input/query/prompt. The description adds no parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description identifies a clear verb-resource pair: it routes a factual question to the right Pipeworx tool and returns a structured answer with citation URIs. It also explicitly differentiates itself from ask_pipeworx_grounded and deep_research, so an agent can tell them apart immediately.

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

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

The description gives explicit when-to-use guidance: prefer over web search for a broad list of domains and starter phrases, start here for most questions, and step up to ask_pipeworx_grounded or deep_research only for specific needs. It even covers breaking-news routing, making the alternates unmistakable.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: candidate routing improvements are enabled live during tests, none is active now (as of 2026-07-26), and it is a full working router with no fallback. This clarifies the dynamic and potentially changing nature of the tool's routing behavior.

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

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

Four sentences that front-load the beta identity and relationship to ask_pipeworx before covering current status and usage. There is minor redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but each sentence otherwise earns its place.

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

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

With no output schema, the description compensates by asserting the same response shape as ask_pipeworx and explaining the experimental status. It gives enough context for an agent to call it confidently, though it intentionally leaves the exact behavior of future candidate changes open-ended.

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

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

Schema covers all six parameters at 100%, including aliases for question. The description adds no parameter-specific detail beyond saying it has the same arguments as ask_pipeworx, so it does not improve on the schema's already-complete parameter documentation.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx: a universal router over the same 5,706 tools with identical arguments and response shape, but with experimental routing improvements potentially active. It explicitly distinguishes from the stable ask_pipeworx sibling by framing it as the 'experimental edge' and noting when it currently matches the stable version.

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 wanting the newest routing, and mentions that results are compared against the stable router. It implies the stable router is the alternative for non-experimental use, though it does not explicitly state 'use ask_pipeworx for stable behavior.'

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, and the description does not contradict any of them. It goes well beyond annotations by detailing the success return shape, explicit refusal contract, enumerated refusal_reason values, evidence as verbatim quote, and the extra LLM call cost. This is rich behavioral disclosure for a complex tool.

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

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

The description is longer than a one-liner, but every sentence carries a distinct piece of information: purpose, routing mechanism, return contract, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose and uses structured formatting like return objects and enumerated refusal reasons to keep information dense without filler.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers what the tool returns, all refusal paths, source/evidence behavior, when to use it, and the cost tradeoff against the sibling tool. An agent has everything needed to invoke it correctly and interpret its results.

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

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

Schema description coverage is 100%, and the schema fully documents the single question parameter and its aliases, so the description does not need to add parameter syntax. The description's high-stakes domain examples add usage context, but they do not alter the semantics of the question field. Baseline 3 is appropriate given full schema coverage.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly defining what the tool does and its scope. It explicitly distinguishes itself from ask_pipeworx by saying it uses the same routing but extracts answers only from tool results, making sibling differentiation explicit.

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

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

It provides explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, with concrete high-stakes examples like financial verdicts, legal claims, medical lookups, and public statements. It also gives a clear when-not-to-use directive by saying to prefer ask_pipeworx for casual lookups and discloses the extra LLM call cost.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: resolver contract, parent event extraction, news fallback, safety short-circuits, wide-spread tradeability, and cancellation rules. 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 verbose but well-structured with bolded section headers and clear examples. It is front-loaded with purpose and usage. Every sentence adds value given the tool's complexity, though it could be slightly more concise.

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

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

The description is exceptionally complete for a tool with 3 parameters and no output schema. It covers resolver confidence, parent events, news fields, safety, spread warnings, cancellation rules, and more. All necessary context is provided.

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

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

Schema coverage is 100%, and the description adds value beyond schema by explaining default behavior (depth default thorough, include_raw default false) and providing context for the market parameter (slug, URL, or question text). The description examples further clarify usage.

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

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

The description states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data research for a given bet.

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 usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes guidance on when to inspect results (check market_match_confidence) and handles edge cases like closed markets, but does not explicitly 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context: for companies it pulls from SEC EDGAR/XBRL with correct off-calendar fiscal years, for drugs from FAERS and FDA, and results are sorted by primary metric. It also mentions citation URIs.

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

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

The description is a single dense paragraph, but it is well-organized with examples first, then behavior, then benefits. It is concise yet comprehensive, though a slight structure with bullet points could improve readability.

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

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

Given the complexity of comparing entities with multiple data sources and no output schema, the description clearly states the return format (paired data + citation URIs), sorting behavior, and data sources. It covers all necessary aspects for correct 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 coverage is 100% with two parameters. The description adds examples of acceptable values for 'values' (tickers/CIKs for company, drug names for drug) and explains what data each type returns. This goes beyond the schema's minimal 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 explicitly states that the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It includes concrete usage examples like 'Compare X and Y' and distinguishes between entity types with specific data sources.

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

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

The description advises to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, claiming it replaces 8–15 sequential lookups. It does not explicitly name alternative tools, but the guidance is clear and actionable.

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

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

Annotations already mark it readOnly/openWorld/idempotent, and the description adds rich behavior beyond that: account requirements and paid tier, parallel routing across 5,706 tools, findings packet composition (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] never invented, contradictions[], hop fields, citation_uri fetchability, semantic excerpting, and latency. No contradiction exists.

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 front-loads the most decision-critical information (account requirement, routing to ask_pipeworx) before the mechanics. Each sentence contributes operational detail for a complex tool; it is dense rather than padded, though slightly longer than strictly necessary.

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 high-complexity tool with no output schema, the description thoroughly covers the findings packet, citation semantics, gaps/contradictions behavior, latency expectations, authentication prerequisites, and depth options. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful detail by explaining depth variants ('standard' re-angles gaps, 'thorough' chases leads and is paid) and noting that broad/multi-part questions are acceptable. It doesn't heavily extend the question param, but the depth semantics are genuinely value-add.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' and explicitly clarifies this is NOT open-web search. It also explains the decomposition/parallel-routing behavior, distinguishing it from sibling tools like ask_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?

Provides explicit when-to-use versus when-not-to-use guidance: best for broad/multi-part structured-data questions; single lookups and breaking/current-news topics should go to ask_pipeworx; unsigned-in users are directed to ask_pipeworx. This covers both exclusions and alternatives clearly.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond by detailing the return format (top-N tools with names, descriptions, schemas) and that results are ready to call, no second schema lookup.

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 (4-5 sentences), front-loaded with core action, and each sentence adds value. No redundancy.

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

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

Given no output schema, the description adequately explains the return format and usage context. However, it does not mention edge cases like empty results or performance, which would push it to 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%, and the description does not add significant semantic value beyond what the schema provides. The schema already documents all parameters and aliases. Description focuses on purpose, not 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 finds/discover tools by describing data or task, and specifies it returns top-N relevant tools with full schemas, ready to call. This distinguishes it from siblings like compare_entities or deep_research.

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 instructs to call this FIRST when many tools are available, and provides examples of when to use (e.g., SEC filings, FDA drugs). Also implies not for direct answers but for tool discovery.

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

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

Adds context beyond annotations: describes fan-out across multiple sources, mentions patents API sunset and soft-fail, and lists returned fields. 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?

Front-loaded with example queries and key instruction. While slightly lengthy, every sentence adds value with minimal 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?

Strong coverage given annotations and schema: safety profile from annotations, param details from schema, and behavioral details from description. No output schema needed for clarity.

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 3. Description adds practical context (e.g., zero-padded CIK) but largely repeats schema. Adds no critical depth beyond what 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?

Description uses specific verb-resource ('full cross-source profile') and lists example queries. Distinguishes from sibling tools like resolve_entity by specifying that names are not supported.

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 to prefer over chaining individual lookups and provides clear exclusion condition: 'names not supported (use resolve_entity first)'.

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 annotations: 'clear sensitive data' and the pairing guidance. Annotations already show destructiveHint=true, so no contradiction.

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

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

Two concise sentences: first states purpose, second provides usage guidelines. 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavior. Contextual completeness is high.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds no additional meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the action ('Delete') and resource ('previously stored memory by key'), and distinguishes it from sibling tools 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly states when to use: 'When context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with 'remember' and 'recall', implying 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?

Describes the fetching, extraction, and output format ('single text blob ready to drop at site-root/llms.txt'), adding context beyond annotations. No annotation contradiction; readOnlyHint and idempotentHint are consistent. Does not detail error handling or rate limits, but acceptable for a read-only tool.

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

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

Four sentences, each serving a purpose: function, process, output format, and use cases. Front-loaded with the main action. No redundant 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 two-parameter tool with no output schema and safe annotations, the description covers purpose, process, output, and use cases adequately. Lacks mention of error handling or prerequisites but overall complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds example for url ('https://example.com') and constraint for max_links ('default 25, max 50'), but this is marginal extra value beyond the schema. 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?

Description clearly states 'Generate a production-ready llms.txt file for any URL' and explains the purpose for AI crawler indexing. It differentiates from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing specifically on generating the llms.txt 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?

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor view. However, it does not mention when not to use this tool or suggest alternatives, which would strengthen 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 safety and idempotency. The description adds that it returns recently submitted malware URLs, which aligns with annotations but does not disclose additional behavioral traits such as rate limits, result ordering, or potential staleness.

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: the first states the action clearly, the second provides a use case. There is no redundant or unnecessary wording, and it is efficiently front-loaded.

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

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

For a simple tool with one optional parameter, an output schema, and no nested objects, the description covers the core functionality and a typical use case. It could mention the output format explicitly, but the output schema fills that 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?

Input schema has 1 parameter (limit) with a description covering its type, default, and max. Schema description coverage is 100%, so the tool description adds no parameter information beyond what is already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves recently submitted malware URLs from URLhaus ('Get a list of recently submitted malware URLs from URLhaus'). It names the specific verb and resource, though it does not explicitly differentiate from sibling tools like lookup_url or recent_alerts that may overlap in functionality.

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

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

The description implies usage for monitoring latest threats ('Useful for monitoring the latest threats.'), but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context by listing specific return fields and usage scenarios, no contradictions.

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

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

Two sentences with no wasted words: first states purpose and return fields, second gives usage guidance. Front-loaded and efficient.

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

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

Given 1 optional parameter and no output schema, description adequately covers return fields and usage context. Could optionally mention parameter behavior, but not required.

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

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

Schema has 1 optional parameter (include_inactive) with description, and schema coverage is 100%. Description does not mention the parameter, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool lists active subscriptions and enumerates return fields (id, type, params, etc.), distinguishing it from siblings like subscribe and unsubscribe.

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

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

Explicitly states when to use it: 'review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention alternatives, but sibling context implies separate tools for other actions.

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, non-destructive. Description adds context about the data source (URLhaus) and explicitly states it returns all known malicious URLs. No contradiction.

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

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

Two sentences, front-loaded with purpose, no extraneous information. Every sentence adds value.

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

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

Simple one-parameter lookup tool with output schema explaining return values. Description covers all necessary context: data source, input, output.

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

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

Schema coverage is 100% with clear description and example. Description adds no further semantics beyond what the schema already 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?

Description clearly states verb 'look up', resource 'hostname or IP address in URLhaus database', and output 'malicious URLs'. Distinguishes from sibling lookup_payload and lookup_url by specifying host lookup.

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?

Context implies usage when you have a host/IP and want associated malware URLs, but no explicit when to use vs alternatives or when not to use. Sibling tools exist for different lookup types, but the description does not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description isn't needed for safety. It adds context about the data source (URLhaus) and output fields but doesn't disclose any additional behavioral traits (e.g., rate limits, authentication). This is adequate 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?

The description is a single, front-loaded sentence that efficiently conveys purpose and results. It is concise without being overly terse, though it could be slightly more structured (e.g., separate result list).

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 an output schema present (even if not shown here), the description sufficiently covers inputs and outputs. It mentions the database and key return fields. It lacks details like number of results or authentication, but for a lookup tool with good annotations, this is nearly complete.

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

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

Schema coverage is 100% and each parameter has a clear description (hash format and length). The tool description does not add extra meaning beyond that, so it meets the baseline but doesn't exceed.

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 action: look up a malware payload by MD5 or SHA256 hash. It specifies the database (URLhaus) and lists the returned fields, distinguishing it from sibling tools like lookup_host and lookup_url.

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

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

The description implies when to use the tool (when you have a hash and need payload info). It doesn't explicitly state exclusions or alternatives, but the sibling context makes differentiation clear. Adding a note that at least one hash is required would improve it.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it queries an external database (URLhaus) and returns specific fields. However, it does not disclose potential rate limits, authentication requirements, or behavior on non-malicious URLs. The description provides some additional context but is not exhaustive.

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: two sentences, the first stating the action and purpose, the second listing return fields. No unnecessary details, and each sentence serves a clear function.

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

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

Given the tool's simplicity (one parameter, annotations indicating safe operation, and an output schema), the description covers the essential aspects. It explains the purpose, the data source, and return values. It could mention limitations or typical use cases, but overall it is adequate for an AI agent to understand and invoke the tool correctly.

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

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

The input schema has 100% coverage for its single parameter 'url', with a clear description and examples. The description does not add extra meaning beyond confirming the parameter is a URL and mentioning the database context. Since the schema already covers the parameter thoroughly, the description adds minimal value here.

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: to look up a URL in the URLhaus database to check for malware. It specifies the database (URLhaus) and the return fields (threat category, status, blacklist status, tags). This distinguishes it from sibling tools like lookup_host or lookup_payload, which target different 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 does not provide guidance on when to use this tool versus alternatives like lookup_host or lookup_payload. It only states what it does, leaving the agent to infer usage context. No explicit exclusions or comparisons are given, which is a gap given the sibling tools.

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

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

Beyond the annotations, the description reveals key behaviors: the claim_token workflow, rate limiting ('Rate-limited to 5 per identifier per day'), and the fact that it's free and doesn't count against quota. It also explains what happens with a claim_token ('Returns the status and, once resolved, what actually changed'), which is not indicated in 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 each sentence provides useful guidance. It front-loads the core purpose and usage, then covers exclusions and workflow details. It could be slightly more scannable with bullet points, but it remains appropriately sized 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 no output schema, the description thoroughly covers the full feedback lifecycle: filing, receiving a claim_token, and later querying status/changes. It addresses rate limits, quota impact, and team review cadence, leaving little ambiguity about expected behavior.

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 input schema has 100% parameter coverage, the description adds critical semantic guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies the claim_token parameter's role, demonstrating usage with a concrete example, which goes beyond the schema's brief 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also distinguishes itself from siblings by explicitly limiting reports to Pipeworx tools and advising against filing issues for other MCP servers.

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?

Detailed when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides explicit exclusions: 'if the tool came from a different MCP server... file it with that server 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 readOnlyHint, openWorldHint, idempotentHint. Description adds value by specifying data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions.

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

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

Three front-loaded sentences: purpose, use cases, technical details. No wasted words.

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

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

Despite no output schema, description adequately covers return structure (top tools, packs, total volume) and parameter semantics. All needed context is present for an agent to invoke correctly.

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

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

Schema has 100% coverage with enum and description. Description adds extra semantic meaning: short vs long windows for hot vs steady-state demand, enhancing the schema's baseline.

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

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

Description clearly states it returns top tools, packs, and call volume over recent windows. Verb-resource pair is explicit, and it distinguishes from sibling tools like lookup/recall by focusing on aggregated trending data.

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?

Three explicit use cases are provided (discovering hot data, confirming canonical tools, aligning use cases). No explicit when-not-to-use, but the tool's niche is clear from context.

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

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

Annotations declare readOnlyHint true, idempotentHint true, destructiveHint false. Description adds substantial behavioral context: checks (monotonicity, partition, fill), thresholds (3pp, 20% placeholder, 0.30 Jaccard), response structure, and trade guidance. No contradictions.

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

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

The description is comprehensive and front-loaded but quite verbose. Every sentence adds value, but could be more concise. Still, it is well-structured and informative.

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 (multiple modes, algorithmic details, response fields) and absence of an output schema, the description fully explains return values, internal checks, and even references a related tool for custom sizing. Complete and 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 coverage is 100% with descriptions for both parameters. Description significantly enriches meaning: explains modes, recommended usage, example slugs, acceptance of full URLs, and the operations performed for each parameter.

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

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

The description clearly states that the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scanning. Also advises when not to trade (realizable edge ≤ 0) and suggests polymarket_fill_risk for custom sizing.

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. Description adds behavioral context: caching at KV level for 1h keyed on all knobs, Fed bets excluded from ranking, and diagnostics provided. 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?

Front-loaded with purpose, then structured sections for model families, edge details, and response format. Dense but every sentence earns its place. Slightly verbose but justified given 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?

Despite no output schema, description details the full response structure (by_segment, fed_candidates, diagnostics) and explains why some segments might be empty. Completely covers what the agent needs to understand return values and 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%; every parameter is described. Description adds significant extra meaning beyond schema types and brief descriptions, e.g., slippage_pp explains typical bid/ask depth, min_liquidity explains walking the book, min_partition_leg_kelly clarifies its application. Schema alone is insufficient without this context.

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

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

Description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. Specific verb ('scan') and resource ('Polymarket markets') with clear value proposition. Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and discovery.

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

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

Explicitly built for 'what should I bet on today' and provides detailed guidance on tradeable-edge knobs and filters. While it doesn't directly compare with siblings, it gives clear context on when to use the tool and how to configure parameters.

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. The description adds significant behavioral detail: daily closes vs intraday, 60-day snapshot TTL, snapshot gaps due to cache-miss, and full response structure. No contradictions with annotations.

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

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

The description is well-structured with a clear introduction, response field details, and limits. It is front-loaded with the core question. Slightly verbose but every sentence adds value; could be trimmed slightly without losing 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 no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and each field's meaning, including trend types and decay calculation. It also covers limitations. Completely adequate for a tool with two optional 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% with parameter descriptions. The description adds context: days default 14 and max 30, window default '1wk' and refers to snapshot family, and explains that decay numbers come from daily closes. This adds meaning beyond schema basics.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific temporal question about edge duration. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description explicitly explains when to use this tool (comparing fresh vs old wide edges) and provides context for interpreting results. However, it does not explicitly list alternatives or when not to use it, though the purpose inherently differentiates it from siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, verdict), and warns about thin legs and partial fills. This goes beyond 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 dense and provides thorough information, but it is verbose with some redundancy (e.g., repeated mentions of partial fills). It could be more concise while retaining key points.

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

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

Despite the lack of an output schema, the description enumerates all return fields for both modes, covers edge cases (thin_legs, forced_directional_risk), and explains the implication of partial fills. It is comprehensive 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%, but the description adds significant value by explaining how size_usd is interpreted differently in single-market vs basket mode, the default logic for side, and clarifying that market and event are mutually exclusive. This enhances the bare 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly defines two modes (single-market and basket/partition) and differentiates from siblings like polymarket_arbitrage and polymarket_edges by emphasizing its role as a pre-trade risk check.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides clear when-to-use guidance and explains why (theoretical overround not capturable, partial fills create directional risk).

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, idempotent, and non-destructive, and the description adds substantial non-obvious behavior: the 2-25pp spread caveat, bet-shape equivalence, compatibility codes, the rule that unknown metric_type/match_subtype legs are never paired, and skip counters. This is exactly the kind of trust-relevant context an agent needs beyond structured annotations.

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

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

The description is long, but the length is earned: it front-loads purpose and modes, then uses capitalized RESPONSE / SAFETY FIELDS / codes sections to organize dense information. The main cost is an agent must parse a heavy block of codes and field names in prose, but there is little redundancy.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, compatibility fields, low_confidence_pairs, temporal_alignment, and skip counters. The main gap is that the schema lists all parameters as optional while the description implies two modes; it never explicitly states whether only one explicit override may be supplied or whether topic and explicit parameters are mutually exclusive.

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, but the description adds meaning by explaining that topic 'auto-fetch[es] the matching event on each venue' and that the explicit parameters override the topic-mapped side. This goes beyond the schema's bare enum and override notes.

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 the exact resource ('cross-venue spread between Kalshi and Polymarket') and scope ('same resolving question'), and the TWO MODES paragraph makes the tool's function unambiguous. It is clear, but it never explicitly contrasts itself with sibling tools like polymarket_arbitrage or polymarket_edges, so differentiation is implied rather than stated.

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 TWO MODES section is genuine decision guidance: use topic shortcuts for pre-mapped macros, or use explicit ticker/slug for custom pairings. The closing warning that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning today is a useful when-not. It does not name alternatives among sibling 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 indicate readOnly and idempotent. The description adds context about scoping (anonymous IP, BYO key hash, account ID) and behavior when key is omitted, adding value beyond annotations without contradiction.

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

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

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

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

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

While missing output format details, the description is complete for a simple retrieval tool. Could mention return type but adequate overall.

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

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

Schema coverage is 100% and description adds meaning by explaining that omitting the key lists all keys. This provides clear guidance beyond the schema's basic 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 verb (retrieve/list) and resource (previously saved memory), distinguishes between retrieving a specific key and listing all keys, and differentiates from sibling tools like remember and forget.

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

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

The description explicitly tells when to use the tool (to look up previously stored context), provides examples, explains scoping, and mentions pairing with remember and forget for a complete workflow.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining the mark_read parameter's side effect (flagging events as read) and the feed's persistence. It does not contradict annotations.

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

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

The description is concise (four sentences) and front-loaded with the primary purpose. Every sentence adds useful information without 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 no output schema, the description adequately explains the return fields (source, citation_uri, raw payload). It covers all 5 parameters (none required) and provides usage guidance (polling, alternative HTTP endpoint). The description is 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 covers 100% of parameters with descriptions. The description adds significant value by providing examples (e.g., 'sec_8k' for type), clarifying the ISO timestamp format for since, and explaining the effect of mark_read on subsequent calls. This goes beyond the schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies what is returned (source, citation_uri, raw event payload) and how to filter. However, it does not explicitly differentiate from siblings like list_subscriptions or subscribe, though the purpose is distinct.

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

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

The description provides context on usage, noting that polling works fine and that the same feed is available via an HTTP endpoint for scripts/dashboards. It implies when to use the tool versus the alternative but does not explicitly state when not to use it or compare with sibling tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true. Description adds valuable context: fans out to multiple sources, explains fallback and soft-fail mechanisms, and describes return structure. No contradiction with annotations.

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

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

Front-loaded with example queries. Every sentence serves a distinct purpose: purpose, sources, parameter formats, return structure, alternative. No wasted words, well-structured for quick understanding.

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

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

Despite no output schema, description fully explains return structure (changes[] grouped by source, total_changes count, citation URIs). Covers source behaviors, parameter formats, and edge cases like USPTO soft-fail. Complete for an agent to use correctly.

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

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

Schema description coverage is 100%. Description adds extra meaning beyond schema: explains 'since' format with relative shorthand examples and recommends '30d' or '1m', clarifies 'value' can be ticker or CIK, and reiterates 'type' limitation.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' from multiple sources, with specific verbs like 'fans out'. It distinguishes itself from sibling 'entity_profile' and lists example queries that match user intents.

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

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

Explicitly provides when-to-use scenarios with example queries. Gives a direct alternative: 'Use entity_profile instead when you want the static profile'. Also explains source behavior (GDELT→GNews fallback, USPTO soft-fail) guiding appropriate 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?

Adds context beyond annotations: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous. Annotations already cover idempotency and non-destructiveness.

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

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

Four sentences, front-loaded with purpose, every sentence adds value. No redundancy.

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

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

Complete for simple tool with two string params and no output schema. Explains storage scope, persistence, and tool pairing.

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

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

Schema has 100% coverage with descriptions for key and value. Description provides example key formats but adds minimal extra meaning beyond schema.

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

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

Clear verb 'save' and resource 'data', explicitly states purpose to reuse later. Differentiates from siblings 'recall' and 'forget'.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall/forget for retrieval/deletion.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, the description adds substantial behavioral context not derivable from those hints. It details the cross-source identity spine, that each identifier is labeled with its source, that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and that LEI/FIGI enrichment degrades gracefully when external services are unavailable. It also mentions cascading internal lookups. These are valuable beyond the annotation flags and contradict nothing.

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 long, but it is well-structured: example queries, supported types with sub-details, graceful degradation note, and efficiency claim. Every sentence contributes useful information for a complex multi-source tool. It loses one point because the wall-of-text style could be more scannable with bullet points, but no sentence is wasted.

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 must explain what the agent can expect. It does so thoroughly: for company it lists CIK, ticker, company_name, LEI, ownership hierarchy, FIGI; for drug it lists RxCUI, ingredient, brand, and citation; it explains the unresolved field behavior and degradation. It also covers edge cases like ISIN-to-LEI for non-US issuers. There is no missing context relevant to invocation or result interpretation.

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

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

With 100% schema coverage, baseline is 3, but the description elevates it. For the 'type' parameter, it elaborates on what each enum value returns (company → CIK, ticker, company_name, LEI, ownership, FIGI; drug → RxCUI, ingredient, brand, citation). For 'value', it gives concrete examples like 'AAPL', '0000320193', 'ozempic', and even an ISIN example, plus explains input flexibility (ticker, CIK, ISIN, or name). This goes well beyond the schema's terse property descriptions.

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

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

The description opens with concrete example queries ('What's the ticker for…' / 'find the CIK for…') and a clear verb phrase: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings like lookup_host or entity_profile by framing itself as the cross-source identity resolver for names. The called-out supported types (company, drug) plus identifier details leave no ambiguity.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' This is a strong when-to-use instruction. It also notes that it replaces 2-3 manual lookups, implying a preferred choice. However, it doesn't explicitly state when not to use it (e.g., when you already have an ID and need a profile) or name alternatives beyond 'other tools.' That missing exclusion keeps it just short of 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable context: it discloses that it probes each entity with ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density). No contradiction with annotations.

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

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

The description is two sentences long, front-loaded with the core purpose ('Compare AI visibility across multiple entities side-by-side'), and contains no filler. Every sentence adds value.

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

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

Despite no output schema, the description specifies return fields (score, confidence, signal density). Parameters are fully documented via schema. The tool's complexity (ranking multiple entities) is addressed, though additional details about sorting or assumptions could improve completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by noting that the first entity is treated as the 'subject' for narrative and mentioning the Anthropic API key requirement. However, parameter descriptions in the schema already provide clear semantics.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. It uses specific verbs and resources ('compare', 'probes', 'ranks') and distinguishes from the sibling tool 'ai_visibility_check' (single-entity) by focusing on multi-entity comparison.

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 provides a use case ('competitive AI-marketing audits') and an example question. It implies usage for comparing entities but does not explicitly specify when to avoid using it or mention alternatives like 'ai_visibility_check' for single-entity 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?

Adds significant behavioral context beyond annotations: fans out across multiple services, partial failures degrade gracefully with 'sources_failed' list, bundlephobia first measurement can take 5-30s. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Description is moderately long but front-loaded with purpose and key details. Each sentence serves a purpose, though some minor redundancy could be trimmed. No wasted words.

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

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

Despite no output schema, the description lists all return fields (summary block, per-advisory, links, alternative versions) and covers edge cases like partial failures and timing. This provides complete context for an agent to understand the tool's behavior and output.

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. Description adds value by clarifying that scoped packages (e.g. '@types/node') are accepted and that version defaults to latest published. This extra context raises the score above baseline.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size metrics. It specifies 'NPM ecosystem only in v1', distinguishing from other ecosystems handled by deps.dev directly. No sibling tool overlaps.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides alternatives for other ecosystems (PyPI, etc.), giving clear guidance on when not to use this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral details: uses BGE-base-en embeddings + cosine similarity over 500-char overlapping windows, input cap of 200K chars with truncation/flagging, and that every passage carries a character offset for verification.

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 (4-5 sentences) and frontloaded with the core action. Every sentence adds value: purpose, usage context, pairing suggestion, technical mechanism, and limitation. No fluff.

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

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

Given the tool's complexity (semantic search, truncation, offsets) and absence of an output schema, the description is remarkably complete. It explains input, output format (passages with offsets and similarity scores), limitations (200K chars), embedding method, and use case.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds meaning beyond the schema by explaining the high-level usage pattern (pass fetched text + query), giving example queries, and clarifying the limit's effect (max passages). This surpasses the baseline of 3.

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

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

The description clearly states the tool's purpose: semantic search inside a fetched record (e.g., SEC 10-K, article) using natural-language queries. It distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded and highlighting the offset feature for verification.

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

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

The description explicitly advises using this tool when a record is too large for the prompt, saving context by returning only relevant passages with offsets. It pairs well with ask_pipeworx_grounded. While it lacks explicit 'when not to use' guidance, the context is clear enough.

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

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

The description adds significant behavioral details beyond annotations: requires OAuth account, delivery constraints (phone verification, 10/day SMS cap, webhook auto-disable after 10 failures), and per-type parameter examples. No contradictions with annotations.

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

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

The description is well-structured with clear sections and front-loaded purpose. It is slightly long but efficiently packs information without redundancy; every sentence adds value.

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

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

Given the tool's complexity (multiple types, nested objects, multiple delivery channels), the description is comprehensive. It covers required parameters, type-specific filters, delivery constraints, and return value (subscription ID). Lacks note on idempotency (annotations indicate idempotent but description does not mention), but otherwise complete.

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

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

The input schema already has 100% description coverage for all parameters. The description enriches semantics by providing concrete examples for each subscription type and detailed delivery channel constraints, adding value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool (to set up proactive monitoring) and requirements (Pipeworx OAuth account). It gives examples for each subscription type but does not explicitly contrast with sibling tools 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds context that it returns category-bucketed examples and is non-destructive. Does not contradict annotations.

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

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

The description is thorough but slightly verbose with multiple alternative phrasings. It front-loads the purpose and is well-structured, though some repetition could be trimmed.

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 onboarding tool with one optional parameter and no output schema, the description covers the use case, return format (categories), and usage context fully. No gaps remain.

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

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

Schema has 100% coverage with a description of the topic parameter. Description adds nuance by stating 'Omit for a cross-category spread,' which is not in the schema. This provides decision guidance beyond enum listing.

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

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

The description clearly states it is the onboarding entry point for a new agent, returning category-bucketed example questions with exact tool calls. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its role.

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

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

Explicitly instructs to use this tool FIRST when the agent does not know what Pipeworx can do, and explains when to omit or include the topic parameter. No guidance on when not to use is needed given its introductory purpose.

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

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

Discloses ownership constraint, deactivation behavior, and link to historical data. Adds value beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). No contradiction.

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

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

Two sentences, no wasted words. Front-loads purpose, then adds constraints and behavior efficiently.

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

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

Covers all necessary information for a simple cancel operation: id, ownership, effect on data, and relation to other tools (recent_alerts). No output schema needed.

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

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

Schema has 100% coverage and describes id as 'Subscription id (uuid) returned by subscribe.' Description adds context that the id comes from subscribe, which is helpful but not essential. Slightly improves over baseline 3.

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

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

Clearly states the action (Cancel) and resource (subscription by id). Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement (only own subscriptions) and behavioral outcome (deactivation, not deletion, preserving history via recent_alerts). Provides when-to-use and when-not-to-use context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral details: the routing logic (SEC vs. grounded pipeline), the meaning of each verdict (especially the crucial caveat that could_not_verify means the check did not happen and is not evidence), and the structure of verification_error. This is substantial value-add 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 longer than average but front-loaded with trigger phrases and purpose. Each section (routing, verdicts, caller warnings, efficiency) serves a distinct function, and the content is highly relevant. It could be slightly trimmed, but complexity justifies the length.

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

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

With no output schema, the description fully explains return values: verdict types, actual value with citation, reasoning, and error details. It covers expected edge cases (unsupported vs. could_not_verify) and gives caller-specific instructions. The tool's complexity is fully matched by the description's coverage.

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

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

The schema already describes both parameters (claim and tolerance_pct) with examples and constraints, so baseline is 3. The description does not add additional semantic depth for these parameters; it mentions 'exact percent-delta math' but doesn't go beyond the schema's explanation of tolerance. Schema coverage is 100%, so no compensation needed.

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: natural-language claim verification against authoritative sources, with explicit trigger phrases and examples. It distinguishes itself from siblings by focusing on fact-checking and mentioning it replaces 4–6 sequential calls, separating it from generic research tools.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and outlines two distinct paths (financial vs. non-financial claims). It also explains how to interpret results like could_not_verify. However, it doesn't explicitly name alternative sibling tools to avoid, so exclusions are implied rather than spelled out.

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