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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond those: the tool autonomously routes to the right sub-tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This meaningfully enriches the operational picture.

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 dense, front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), followed by scope, examples, and alternative routing. Some redundancy exists between 'PREFER OVER WEB SEARCH', 'Use whenever', and 'START HERE', but each section contributes useful guidance and the structure is scannable.

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 a single required parameter and no output schema, the description is highly complete: it covers when to use, what to ask, how it behaves, what output to expect (structured answer with citations), and how it compares to closely related sibling tools. Nothing essential is missing.

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

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

Schema coverage is 100% (the single meaningful parameter 'question' and its aliases are fully described). The description goes well beyond the schema by detailing the kinds of natural-language questions accepted, the domains covered, and concrete examples. This helps an agent formulate valid inputs much better than the schema alone.

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

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

Clearly states a specific verb ('routes', 'returns'), a precise resource ('5,798 tools across 1,517 verified sources'), and the exact scope: current or historical factual data across many listed domains. It strongly differentiates from web search and sibling tools like ask_pipeworx_grounded and 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 says 'PREFER OVER WEB SEARCH', lists trigger phrases and examples, and names the conditions for switching to alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. No inference is required.

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 this tool read-only, idempotent, open-world, and non-destructive, and the description adds meaningful live-behavior context: candidate routing improvements are enabled only during tests, no candidate is active right now, and it is a full working router rather than a fallback. This gives the agent crucial expectation-setting beyond what annotations alone provide.

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

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

The description is compact and front-loads identity, scope, and current behavior in the first two sentences. The remaining sentences add operational guidance about when to use it and its full working status. There is slight redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but the overall structure remains efficient.

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

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

For a tool with no output schema, the description supplies essential operational context: it is a working router, its response shape matches ask_pipeworx, and its behavior is currently identical to the stable version. It references ask_pipeworx and the schema already covers parameters, so an agent has enough to invoke it correctly, though a direct statement of the response format would make it fully self-contained.

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

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

Schema description coverage is 100%: the question parameter and all aliases are already documented in the schema. The tool description simply says 'same arguments' without adding format, defaults, or usage nuance, so it adds no real value beyond the schema. This meets the baseline for a fully covered schema.

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

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

The description opens by identifying the tool as the beta version of ask_pipeworx and defines it as a universal router with the same 5,798 tools, arguments, and response shape. It also distinguishes this variant from the stable sibling by explicitly mentioning 'candidate routing improvements' and 'the experimental edge,' leaving no ambiguity about what the tool does or how it differs.

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 a clear usage criterion: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide what merges, which helps the agent understand the selection context. It does not explicitly state a when-not-to-use case, but the stable router comparison makes the intended choice clear.

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

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

Beyond annotations, the description discloses that the tool refuses rather than fabricates when data is insufficient, enumerates the exact refusal reasons, and specifies the success return shape with evidence/verbatim quote. It also notes the extra LLM call cost. No contradiction with the read-only, idempotent, open-world annotations.

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

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

The description is dense but every sentence contributes: purpose, routing behavior, return/refusal contract, use cases, and cost/alternative guidance. Structured return shapes are presented compactly and the core intent is 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?

Given a single required parameter, rich annotations, and no output schema, the description fully covers what an agent needs: how the answer is grounded, what success and refusal responses look like, when to use it, and when to prefer the sibling tool. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema already fully documents the 'question' parameter and its aliases. The description does not add parameter-level detail, but given full schema coverage the baseline of 3 is appropriate; no compensation is 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 states a specific verb ('ask'), resource ('Pipeworx'), and mode ('grounded' / hallucination-resistant), and explicitly contrasts it with 'ask_pipeworx' by pointing out this mode extracts answers from only tool results. This makes it clearly distinguishable from sibling tools without needing to inspect schemas.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples like financial verdicts and legal claims. It also tells the agent to prefer ask_pipeworx for casual lookups, naming the alternative and the cost trade-off.

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?

The annotations already mark this as read-only and non-destructive, but the description adds significant behavioral context: it decomposes and routes to tools in parallel, returns a findings packet with gaps[], never invents findings, may return contradictions[], and explains latency expectations. This goes well beyond what the annotations provide and matches the read-only, idempotent intent.

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 nearly every sentence provides distinct operational or routing value. It is front-loaded with account requirements and starts the core purpose immediately, though the long parentheticals and repeated depth explanations make it slightly heavier 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 complex tool with no output schema, the description is remarkably complete: it covers auth, tier restrictions, alternatives, return structure, gaps/contradictions behavior, citation fetchability, excerpting behavior, and expected latency. An agent has everything needed to decide whether to call it and how to interpret the result.

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

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

The input schema already documents both params at 100% coverage, so the baseline is 3. The description adds value beyond the schema by clarifying that 'thorough' requires a paid plan, explaining what each depth level does in behavioral terms, and emphasizing that the 'question' param is meant to accept broad/multi-part natural language. That extra context earns a 4.

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

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

The description precisely names the tool's job: grounded multi-source research across Pipeworx's 1,517 structured data sources in one call. It explicitly contrasts itself with open-web search and gives a concrete example of the question type it serves, making it easy for an agent to distinguish from siblings 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?

Usage guidance is explicit and actionable: it tells the agent to use ask_pipeworx when not signed in, to use ask_pipeworx for single lookups, and to use deep_research for broad/multi-part structured-data questions. It even notes that the 'thorough' depth requires a paid plan, preventing failed or unexpected calls.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description richly discloses behavior: it fans out across multiple sources, explains that empty sections are 'a real no-data, not a bug,' mentions the USPTO PatentsView API sunset with soft-fail, and details the private-company resolved:false outcome. This level of behavioral context is 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 long and dense, but every sentence carries operational meaning—sources, return fields, failure semantics, and parameter behavior are all packed in. It is front-loaded with trigger phrases and the core 'full cross-source profile' concept, though the stream-of-consciousness structure could benefit from minor formatting breaks.

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

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

With no output schema, the description fully covers the return structure (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed). It also covers edge cases like soft-fails, empty sections, private companies, and source fallbacks, making it complete for an agent to call 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 already covers 100% of parameter meaning, but the description adds concrete examples (ticker, CIK, name), explains that type accepts 'company' or 'ticker' interchangeably, and clarifies how names resolve via SEC EDGAR. This is additive value beyond the schema.

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

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

The description states a specific purpose: 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete trigger examples like 'brief me on Tesla' and 'company profile for Microsoft.' It also differentiates the tool from chaining single-pack lookups, making its role distinct from generic research siblings.

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

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

The description gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' along with usage examples and clear input flexibility. However, it does not explicitly exclude sibling tools like compare_entities or resolve_entity, leaving some differentiation to inference.

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?

Despite annotations already declaring readOnly, openWorld, idempotent, and non-destructive behavior, the description adds extensive behavioral detail: identical matcher in both modes, compatibility codes, unclassified legs never being paired, temporal alignment null semantics, Kalshi fees not being modeled, and gross vs net spread. It also explicitly warns that compatibility fields can be non-empty even when matches are returned, which is beyond what annotations convey.

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

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

The description is long but well structured with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, spread.fees_note). Each sentence mostly earns its place given the tool's complexity, but there is some repetition around temporal alignment warnings appearing both in the global code list and the per-entry flags, which makes it denser than 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?

With no output schema, the description fully carries the burden of explaining the response shape: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, temporal_alignment, and fees_note. It also covers edge cases and limitations, including what null means and what codes appear when. Nothing critical for a caller to select and invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds meaningful semantics on top: `topic` auto-fetches the matching event on each venue, explicit parameters override the topic-mapped side, and both modes run the identical token-overlap matcher. This goes beyond the schema's individual field descriptions, though the schema already does most of the naming work.

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 first sentence states a specific analytical resource—the cross-venue spread between Kalshi and Polymarket for the same resolving question—with a clear scope and explicit output. The two mode descriptions further pin down exactly what the tool accepts and returns, and the caution that pre-mapped topics are not automatically tradeable removes ambiguity about what it is for.

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 clear when-to-use guidance: use `topic` for pre-mapped macro shortcuts and explicit ticker/slug parameters for custom pairings, and it notes both run the same matcher. It also warns that most pre-mapped topics currently return compatibility warnings. However, it does not contrast this tool with sibling tools like polymarket_arbitrage or polymarket_edges, so the alternative-selection guidance stops 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 with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: internal multi-endpoint cascading, graceful degradation for GLEIF/OpenFIGI unavailability, ambiguity handling via `figi_candidates`, explicit `unresolved` fields, source-labeled identifiers, and ISIN-to-LEI resolution. There is no contradiction with annotations.

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

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

The description is long and dense, but it is front-loaded with examples and organized into clear sections (SUPPORTED TYPES, degradation behavior, input restrictions). Every section adds operational value, though some parenthetical chains are heavy and could be tightened 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?

With no output schema, the description carries the responsibility for return semantics, and it covers them thoroughly: `figi_candidates` for ambiguous matches, `unresolved` for unresolved identifiers, source labels, and behavior when enrichment sources are down. It also documents both entity types and valid input forms, leaving no critical gap for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond schema descriptions. For `value`, it provides examples (AAPL, 0000320193, ozempic), the 'ENTITY NAME ONLY' rule, and a concrete trap: trailing security-class words match nothing. For `type`, it explains what each enum value resolves to and the sources involved, adding meaning the schema alone lacks.

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 user utterances and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates supported types ('company', 'drug') and explicitly frames the tool as the identifier-resolution step, which distinguishes it from siblings like entity_profile or 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?

It gives strong usage direction: 'Use FIRST whenever you have a name but need an ID' and explains when company vs drug applies, plus warns against passing full noun phrases. However, it does not name sibling alternatives or explicitly state when not to use this tool in favor of a sibling, so it falls just short of a 5.

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

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

Annotations already declare 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.