Ukhsa

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 substantial value: it explains the default free model, the optional paid integration via _apiKey (including cost implication), and details the return structure (score, confidence, signals, raw_response per model + combined view). 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 four sentences, highly efficient. The first sentence immediately states the core purpose and output. Subsequent sentences provide essential details (default model, optional key, return structure, use cases) 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 the moderate complexity (4 parameters with a conditional dependency) and the absence of an output schema, the description covers all essential aspects: purpose, parameter roles (including key handling), return fields, and use cases. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances understanding by clarifying the free vs. paid distinction for models, explaining that _apiKey is only needed when probing Anthropic and is passed directly, and adding context on how the 'context' parameter helps disambiguate. These go beyond schema descriptions.

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

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

The description clearly specifies the action ('probe one or more LLMs'), the resource ('business/brand/product/topic'), and the output ('score visibility 0-100 per model'). It distinguishes from siblings by explicitly listing use cases like AI-marketing audits, pre-launch brand checks, and competitive monitoring, which are not covered by other 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 provides clear context for when to use the tool (AI-marketing audits, brand checks) and explains model options (free Workers AI vs. paid Anthropic with BYO key). However, it does not explicitly exclude alternative tools or state when not to use it, missing a bit of directiveness.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about routing to 5,529 tools, filling arguments, returning pipeworx:// citation URIs, and working on every tier with one fast call. This goes beyond annotations but could still mention limitations or rate-limit behavior.

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

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

The description is longer than typical but front-loads the most crucial instruction ('PREFER OVER WEB SEARCH'). The examples and alternative-tool guidance are valuable and earn their place; however, the category list is somewhat repetitive and could be tightened without losing meaning.

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 lacking an output schema, the description explains the return format (structured answer with citations), routing behavior, tier accessibility, and alternative tools for different needs. It covers both primary use cases and edge cases like breaking news, making it highly complete for a meta-tool.

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

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

Schema description coverage is 100% and all parameters are aliases for the single `question` field. The description reinforces the natural-language nature with many concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), which helps clarify usage beyond 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?

The description clearly defines the tool as a factual question-answering router that queries thousands of authoritative sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by stating when each should be used, making the purpose and scope unmistakable.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and even instructs when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also covers breaking-news scenarios, offering clear decision rules.

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 (readOnlyHint, openWorldHint, etc.), the description discloses key behavioral context: it is a full working router with no fallback, candidate routing improvements are only enabled during tests, and currently no candidate is active so it matches ask_pipeworx exactly. It also explains the comparison against the stable router for merge decisions.

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, with the key fact (beta version) front-loaded. Each of the four sentences adds unique value: identity, current state, usage guidance, and reassurance that it is a full router. No redundancy or filler.

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

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

For a beta tool without an output schema, the description fully covers the essential context: it is a full router, experimental, currently identical to ask_pipeworx, and used for testing routing improvements. It even mentions the retirement date of the last candidate, providing complete situational awareness.

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 description covers 100% of parameters (question and its aliases), so the description does not need to add much. It mentions 'same arguments' as ask_pipeworx, which adds minimal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tools and arguments. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental nature and candidate routing improvements.

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 it exactly like ask_pipeworx when you want the newest routing,' giving clear when-to-use guidance. It implies the alternative of using the stable ask_pipeworx when not wanting experimental routing, but lacks a direct when-not-to-use statement.

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 (readOnlyHint, idempotentHint), the description discloses the refusal mechanism with specific refusal_reason values, the strict grounding to tool results, the return payload fields, and the extra LLM call cost. This significantly enriches the behavioral understanding without contradicting annotations.

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

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

The description is a single dense paragraph that front-loads the core purpose and key differentiator. Each sentence contributes substantive information, though it is longer than minimal examples. Slight verbosity is justified by the 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?

The description fully compensates for the lack of an output schema by detailing the return fields, refusal reasons, success case, cost, and usage context. For a complex tool with high-stakes use cases, this is complete and actionable.

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, with all parameters documented as aliases for 'question'. The description adds no additional parameter-specific details, but the schema already fully explains the parameters. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' with a specific verb ('extracts the answer') and resource connection (tool result). It explicitly differentiates from sibling 'ask_pipeworx' by noting same routing but grounded extraction, making its purpose unambiguous.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It names the alternative tool and provides concrete use cases, leaving no ambiguity.

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 extensive behavior beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback fields, safety short-circuits, bid/ask/spread data, and cancellation rule parsing. No contradiction with annotations (readOnlyHint, 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?

The description is verbose and covers many details (resolver, parent event, fan-out examples, safety mechanisms). While front-loaded with the purpose, it could be more concise for an AI agent, but the length is justified by 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?

Given no output schema, the description thoroughly explains response shapes (market details, analysis, evidence fields), resolver contract, parent event extractor, news fields, and edge cases. An agent has enough context to use the tool correctly and interpret results.

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

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

All 3 parameters are described in the schema (coverage 100%). The description adds contextual examples and explains the depth parameter's behavior (quick vs thorough) and the include_raw parameter's effect on response size, providing value beyond the schema definitions.

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

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

The description states the tool researches a Polymarket bet by pulling Pipeworx data, takes a slug/URL/question text, and returns an evidence packet and comparison. It clearly defines its scope and is distinct from sibling tools like polymarket_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?

Explicitly advises using for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Provides context on when results may be blocked (low confidence, closed markets, wide spreads) but does not contrast with sibling 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?

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds rich behavioral detail: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and return of paired data with citation URIs. 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?

A single, well-structured paragraph that front-loads the most important information (purpose, usage priority). Every sentence adds value; no filler. Examples and directives are integrated naturally.

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 explains return format, sorting, and data sources. It covers the most common use cases and edge cases (fiscal year handling). Combined with strong annotations, the description is fully 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 coverage is 100% with good parameter descriptions. The description goes further by explaining what each type ('company' vs 'drug') returns, the data sources, and the behavior with fiscal years. This adds significant meaning beyond the schema.

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

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

The description uses multiple natural language triggers ('Compare X and Y', 'X vs Y', 'which is bigger') and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It clearly identifies the tool's purpose and distinguishes it from siblings like sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong guidance on when to use. Also lists example query patterns that trigger this tool, making it easy 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?

Huge transparency value beyond annotations: account/paid-tier requirements, explicit negation of open-web search, parallel decomposition across 5,529 tools, gaps[] never-invented guarantee, second-hop iteration, contradictions[], semantic excerpting, latency expectations, and citation fetchability. No contradiction with the readOnly/idempotent/openWorld 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?

Dense but well-structured. It front-loads the critical account requirement and packs many essential behaviors into a readable flow using semicolons and parentheticals. It is long, but the complexity of the tool justifies the length; every section adds unique 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 there is no output schema, the description fully compensates by describing the return packet contents: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], and contradictions[]. It also covers latency, pagination-like behavior, and pricing tiers, making the tool's behavior complete for an agent.

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

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

While the schema already describes both params (100% coverage), the description adds substantial meaning: depth levels are explained as quick/standard/thorough with facet counts, hop behavior, gap recovery, and contradications[] scan, plus examples of what the 'question' parameter can accept. This goes well 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly contrasts with open-web search and distinguishes from sibling tools like ask_pipeworx, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data') and when-not-to-use guidance with named alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also notes account/plan prerequisites.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' enhancing transparency.

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

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

Front-loaded with purpose, well-structured, but listing many domains makes it slightly verbose. Still efficient and clear.

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

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

Despite no output schema, description explains return format and usage context. With good annotations and 100% schema coverage, the description is 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%, so schema documents all parameters. Description does not add extra meaning beyond listing domains and mentioning 'Natural language description' in the schema description. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and says 'Call this FIRST when you have many tools available,' distinguishing it from sibling tools.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so description's mention of a parallel, non-destructive call is consistent. Adds context like USPTO API sunset (soft-fails) and data source ordering, enhancing transparency 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?

Well-structured, starting with use cases and examples, then detailing data sources. Every sentence adds value, though slightly dense could be trimmed slightly without losing meaning.

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

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

Despite no output schema, the description thoroughly explains return structure (cik, company_name, filings with URIs, fundamentals, patents with sunset, news, LEI), covers edge cases (names not supported, soft-fail), making it complete for a complex tool.

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

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

Schema coverage is 100%, and the description adds extra meaning: type is only 'company', value accepts ticker or CIK (not names), with examples. This adds significant value beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with specific examples like 'Tell me about X', 'research Acme', etc. It lists data sources and returned fields, distinguishing it from siblings like compare_entities and resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and gives a when-not: 'names not supported (use resolve_entity first)'. This provides clear guidance on when to use this tool vs 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?

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' context but does not significantly expand 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?

Two sentences: first states purpose, second gives usage. No fluff, 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 one-param, no-output tool with clear annotations, the description provides all necessary context for selection and use.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. Description does not add extra parameter details 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 deletes a memory by key, distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and suggests pairing with remember and recall.

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 explains the process (fetches page, extracts title/description/key links, emits markdown) and the output format. Annotations already declare readOnlyHint and idempotentHint, so the description adds value by detailing the extraction behavior without contradicting annotations.

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

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

The description is a single, well-organized paragraph with no redundant sentences. It front-loads the core action and output, then provides use cases 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?

Despite no output schema, the description specifies the output as 'a single text blob ready to drop at site-root/llms.txt', which is sufficient. The tool's behavior is fully explained given its simplicity.

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 describes both parameters fully. The description adds contextual detail: default and maximum for max_links, and clarifies the url parameter scope. This goes beyond 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?

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the verb 'generate', the resource (URL), and the output format. It distinguishes itself from siblings by focusing on AI crawlers and llms.txt creation.

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 lists three explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. Although it does not explicitly state when not to use, the use cases provide clear guidance on applicability.

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 value by explaining pagination, return format (count, next, previous, results[]), and detailed fields per observation, which goes 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 four sentences, front-loaded with purpose and requirements, followed by pagination info and an example. It is efficient but could be slightly more concise without losing clarity.

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

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

Given the complexity of 9 parameters, no output schema, and the need to understand pagination and result fields, the description is complete. It explains required and optional parameters, pagination behavior, and the structure of return data.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces parameter meaning via an example and mentions required levels, but does not add new 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?

The description explicitly states 'Pull the time series for one fully-specified UKHSA metric', providing a specific verb and resource. It distinguishes from sibling tools like list_metrics by emphasizing the requirement of all six levels for a single metric.

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

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

The description clearly states requirements (all six levels) and optional filters (year, page size), and provides an example. It does not explicitly contrast with alternative tools like list_metrics or compare_entities, but the context is well implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns metric names 'ready to pass to get_metric_data', which is useful but does not disclose additional behavioral traits like whether it caches or has rate limits.

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, but the second sentence partially repeats the first. It is front-loaded with purpose and alternative, yet could be merged to remove redundancy.

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

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

Given no output schema, the description explains the return format (metric names like examples) and ties it to get_metric_data. It lacks mention of list size or pagination, but for a simple list tool, this is adequate. Sibling tools provide relevant context.

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

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

Schema coverage is 100% with descriptions for all five parameters. The description restates them collectively as 'five levels' but adds no new semantic meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states it is a 'shortcut' to list all available metric names for a fully-specified location, avoiding iterative navigation via navigate. It explicitly names the output format (metric names ready for get_metric_data) and the five required levels, distinguishing it from sibling tools like navigate.

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 'when to use': when you have a fully-specified location, as an alternative to calling navigate iteratively. It does not explicitly list when not to use, but the context (seamless shortcut) is sufficient for an agent to decide.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world aspects. The description adds that by default only active subscriptions are returned and explains the include_inactive parameter, plus lists the fields in the response.

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 extraneous information. Purpose and usage are immediately clear and front-loaded.

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

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

Despite no output schema, the description lists all returned fields, covers the parameter, and provides usage context. For a simple listing tool, this is fully adequate.

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

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

The single parameter is fully described in the schema (100% coverage). The description adds context about 'active' vs 'inactive' but does not significantly extend the parameter semantics beyond the schema.

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

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

The description clearly states it lists active subscriptions and enumerates returned fields. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on review and retrieval.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for invocation relative to 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 readOnlyHint=true, destructiveHint=false, so the lack of mutation is clear. The description goes beyond annotations by detailing the step-by-step behavioral flow, the return format ({name, link}), and the order dependency of parameters. It does not contradict annotations (no destructive or read-write claims), and adds useful transparency about how the tool chains to other tools.

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

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

The description is a single paragraph of about 110 words, which is compact for a hierarchical navigation tool. Sentences build logically from overall purpose to specific examples. It could be slightly tighter (e.g., 'feed the chosen name into the next-level arg' is slightly wordy), but every sentence adds value. No redundancy or filler.

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

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

Given the tool's complexity (5 parameters, hierarchical dependency, no output schema), the description is remarkably complete. It explains the entire usage flow, return shape ({name, link}), and connection to the downstream tool get_metric_data. Combined with the well-annotated schema and annotations (readOnlyHint, idempotentHint), the agent has all necessary information to use this 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 covers all five parameters with 100% description coverage, but the descriptions are minimal (only example values). The tool description compensates by explaining the logical order and dependencies: 'Pass the levels you already know (in order...)' and 'with no args it lists themes.' It also clarifies constraints like 'Requires theme + sub_theme' for topic and 'Requires the levels above' for geography. This transforms the schema from a list of fields into a usable sequence.

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

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

The description uses specific verbs ('walk', 'discover', 'list') and clearly identifies the resource: the UKHSA surveillance hierarchy. It explains that the tool returns options for the next level based on currently known levels, and gives explicit examples of the hierarchy (theme, sub_theme, topic, geography_type, geography, metrics). This differentiates it from siblings like get_metric_data or list_metrics, which are for obtaining data rather than browsing the hierarchy.

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: to discover valid values for the next level in the hierarchy. It provides a clear step-by-step progression (no args → themes, theme → sub_themes, etc.) and even tells the user to call get_metric_data after obtaining all six levels. This gives strong usage context, though it does not explicitly mention when not to use it (e.g., if you already know all values), so it misses full exclusion 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?

The description discloses several behavioral traits beyond the annotations: the claim_token workflow, that feedback is read daily and influences roadmap, rate limiting to 5 per identifier per day, free usage, and the instruction not to paste end-user prompts. These are operational details an agent needs to use the tool correctly.

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 every sentence serves a purpose, covering purpose, usage boundaries, workflow, and rate limits in a logical order. The 'Not sure?' clarification and the daily-digest note are valuable rather than filler. Slightly dense but not bloated.

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

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

Despite having no output schema, the description fully explains the return value (claim_token) and how to use it later to read resolution status. It covers all four parameters, the nested context object, and operational constraints. An agent has everything needed to invoke the tool correctly without further discovery.

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 in the schema. The description adds meaningful semantic guidance: clarifies how claim_token is used to later check status, explains context is optional structured info, and emphasizes that feedback must reference Pipeworx tools/packs rather than end-user prompts. This exceeds the schema's baseline descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling query tools by framing itself as feedback/reporting rather than information retrieval.

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

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

Provides explicit usage criteria: when to use (bug, feature, data_gap, praise) and when not to use ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies ambiguity with 'Not sure? Pipeworx tool names are the ones this connection lists.' This is model guidance with clear exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and output structure (pack, tool, count). 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 concise paragraphs, front-loaded with purpose, followed by bulleted use cases and additional details. Every sentence is informative with no redundancy.

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

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

With one optional parameter, no required params, full schema coverage, and no output schema, the description sufficiently explains return values (top tools, top packs, call volume) and behavior. Simple tool, complete 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?

Schema covers 100% of parameters with description. Description adds guidance on window selection ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which is helpful but not essential 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?

Description clearly states the tool returns trending data (top tools, packs, call volume) and distinguishes from siblings by focusing on aggregate signal of what other agents are using. Use cases like 'discovering hot data sources' and 'confirming popular tool' further clarify purpose.

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

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

Provides three explicit use cases, but does not mention when not to use or compare to alternatives like discover_tools or ask_pipeworx. However, the context is clear enough for an agent to infer appropriate usage.

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

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

The description discloses detailed behavioral traits, including core logic, response fields, and fill-check conditions. It warns about not trading when realizable_edge_pp ≤ 0. Annotations are consistent (readOnlyHint true), and the description adds significant context beyond them.

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

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

The description is thorough and well-structured, with information front-loaded. Every sentence adds value, but it is somewhat lengthy due to the detailed logic. Given the complexity, this is appropriate.

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

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

Given the tool's complexity and the absence of an output schema, the description fully compensates by explaining return values, modes, and edge cases. It covers all necessary information for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description adds critical meaning by explaining the semantic difference between event mode (single event, walks child markets) and topic mode (cross-event scanning). It also clarifies recommended usage and internal processing.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This specific verb+resource description distinguishes it from siblings 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?

The description explicitly explains when to use each mode (event vs. topic), recommends event mode for specific markets, and provides guidance on alternatives (e.g., 'For custom sizing use polymarket_fill_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?

The description goes far beyond the annotations (which are already readOnly, openWorld, idempotent) by detailing internal algorithms (lognormal barrier, GDELT ratio, partition_overround with per-sport α), response structure (by_segment, fed_candidates, _diagnostics), caching policy (1h at KV level), and knob behavior. It also explains why Fed bets are excluded, adding trust and transparency.

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

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

The description is long but well-structured: purpose first, then model families, response format, knobs, and diagnostics. Every section adds necessary detail for a complex tool with 9 parameters. It is front-loaded with the core value proposition. Slight verbosity in listing model families could be trimmed, but clarity is maintained.

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

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

Given the tool's complexity (three model families, eight data outputs, nine knobs) and no output schema, the description fully explains what the tool returns (edge_pp_net, kelly_fraction, etc.) and why. It also covers edge cases (e.g., Fed bets excluded, partitions with >20% placeholder fraction skipped). No gaps remain for an agent to misinterpret.

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

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

All 9 parameters already have descriptions in the input schema (100% coverage), so the description's job is to add nuance. It does so effectively, e.g., explaining slippage affects ranking and Kelly sizing, min_liquidity prevents walking the book, and min_partition_leg_kelly applies to per-leg Kelly within partitions. These enrich the schema without redundancy.

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 starts with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's unique value (what should I bet on today) and differentiates from generic market scanning tools by detailing three specific model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) that process data differently.

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

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

The description gives a clear use case ('what should I bet on today') and explains the tool avoids paging through hundreds of markets, but it does not explicitly state when to avoid this tool or what sibling tools to use instead. Alternatives like polymarket_arbitrage or polymarket_edge_tracker exist but are not mentioned.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds rich behavioral detail: snapshot mechanism, cache-miss gaps, response structure (tracked, expired, snapshot_dates), and decay computation. 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?

Front-loaded with core question, then details response and limits. Some redundancy (e.g., 'decay_pp_per_day ... both computed on |edge_pp_net|') but overall efficient for the detail provided.

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 missing output schema, description fully specifies response fields (tracked, expired, snapshot_dates) and their subfields (first_seen, trend, decay_pp_per_day, lifespan_days). Also covers limits (60-day TTL, snapshot start). Complete for 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?

100% schema coverage, but description adds meaning: defaults (days=14, window='1wk'), constraints (days max 30), and explanation of 'window' as snapshot family. Goes 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?

Clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific temporal question about edge longevity. Distinct from sibling tool polymarket_edges which likely provides current edges only.

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?

Implicitly guides when to use (for historical persistence, differentiating fresh vs stale edges) and contrasts with new edges. Does not explicitly name alternatives but context is clear.

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

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

Annotations already convey readOnly, idempotent, non-destructive. The description adds behavioral details: it 'walks the ladder', returns fill quality metrics (top_of_book, vwap_fill_price, slippage_pp), and warns about thin books and forced directional risk. 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 front-loaded with the core purpose and then details. It is slightly verbose but every sentence adds value. Could be improved by breaking into sections (e.g., single-market, basket), but overall concise for the 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, the description enumerates return fields (top_of_book, vwap_fill_price, etc.) and covers edge cases (thin_legs, forced_directional_risk). It explains the risks of partial fills. Lacks explicit return structure format, but is adequate for a risk-check tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor nuance (e.g., size_usd as 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional' in basket mode), but most parameter meaning is already in the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the verb 'check' combined with 'fill risk' accurately conveys the function. It differentiates from sibling tools like polymarket_arbitrage and polymarket_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?

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to use it implicitly by highlighting consequences of not using it (partial basket fills converting arb into unhedged direction).

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

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

Beyond annotations (readOnly, idempotent), the description explains compatibility_warning, temporal_alignment, and skipped_cross counters, disclosing edge cases like non-equivalent bet shapes or misaligned resolve periods. 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 front-loaded with purpose and modes, then details response fields and safety conditions. It is dense and informative, though the final sentence is slightly repetitive. Each section earns its place, but some sentences could be 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?

Given no output schema, the description thoroughly explains the response structure (leg prices, spreads, compatibility, temporal alignment, skipped counters) and covers edge cases. For a tool with 3 optional parameters, this is more than sufficient 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 coverage is 100%, so parameters are already documented. The description adds value by explaining how the two modes interact (explicit overrides topic) and illustrates with examples, but does not add significant new parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, distinguishes it from sibling tools like polymarket_arbitrage (single-venue), and immediately specifies the two operating modes. The verb 'spread' and resource 'cross-venue' are explicit.

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

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

The description details two usage modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics may not yield tradeable spreads. It implicitly guides use but does not explicitly mention when not to use or list alternative tools for intra-venue arbitrage.

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

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

Annotations already declare readOnly/indempotent/non-destructive. Description adds scoping to identifiers and the behavior of omitting key (list all). 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 core function, second provides usage guidance and pairings. Front-loaded with key 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 single-parameter tool without output schema, the description covers purpose, usage scenarios, scoping, and sibling relationships completely.

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 description for 'key' property. The overall description adds meaning by explaining the effect of omitting the argument and providing real-world examples, going beyond schema documentation.

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

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

The description clearly states the tool's verb ('Retrieve') and resource (values saved via remember), and distinguishes between two behaviors (value retrieval vs. listing keys). It also separates from sibling tools by mentioning 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?

Provides clear context on when to use (look up stored context, avoid re-derivation) and mentions scoping. Implicitly tells when not to use (when saving or deleting), but lacks explicit exclusion or alternative naming.

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, idempotent, and non-destructive behavior. The description adds behavioral context beyond annotations by explaining the return structure (source, citation_uri, payload), the effect of mark_read on subsequent calls, and the unread_only filter. 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 four sentences, concise and front-loaded. The first sentence states the primary purpose, the second explains return fields, the third lists filters, and the fourth addresses polling and alternative access. Every sentence adds value with no redundancy.

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

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

Given the tool has 5 optional parameters, no output schema, and annotations, the description covers the core behavior well: return structure, filtering, mark_read mechanics, and polling. Minor gaps include not explaining the 'read' state lifecycle or unread_only details, but overall sufficiently 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%, but the description adds extra semantic value by providing examples (e.g., 'sec_8k' for type), explaining the purpose of mark_read to flag events read, and clarifying the limit range (1-200, default 50). This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the verb 'Pull' and resource 'fired events from your subscription feed'. It distinguishes from siblings by focusing on recent alerts with source, citation_uri, and raw event payload, and notes an alternative access method.

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

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

The description provides clear context for usage, including filtering by type and ISO timestamp, the mark_read behavior, and polling suitability. It mentions an alternative endpoint for scripts/dashboards, but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate read/ idempotent hints; description adds details about fan-out to multiple sources, fallback logic, USPTO soft-fail, date format handling, and output structure (changes[] grouped, count, citations). 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 detailed and well-structured, front-loading purpose and usage. Every sentence adds value, though slightly longer than strictly necessary for conciseness.

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

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

No output schema exists, but description fully explains return format (changes[], count, citations) and covers source-specific behaviors (fallback, soft-fail). Complete for a complex multi-source tool.

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

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

Schema has 100% coverage with descriptions; description adds richer context for `since` (ISO/relative examples, '30d' tip) and `value` (ticker or CIK). Goes beyond schema requirements.

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 returns a change feed for a company in a given time window, fanning out to multiple sources. It explicitly distinguishes from sibling tool entity_profile for static profiles.

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

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

Provides explicit usage examples ('What's new with X', 'latest on Y') and directly tells when to use entity_profile instead. Also explains fallback behavior between GDELT and GNews.

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

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

Discloses storage as key-value pairs scoped by identifier, persistent for authenticated users vs. 24-hour retention for anonymous sessions. Adds value beyond annotations by clarifying lifecycle and access boundaries.

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 focused sentences: purpose first, usage scenario, behavior details, and pairing tools. No fluff or repetition.

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

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

Given only two required string params and no output schema, the description fully covers storage semantics, scope, pairing with recall/forget, and retention policy.

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

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

Schema already describes both parameters (key and value) with 100% coverage. The description adds practical naming examples and clarifies that value can be any text, providing slight additional 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 starts with a clear verb-resource combination ('Save data the agent will need to reuse later') and immediately distinguishes itself from siblings ('recall', 'forget') by specifying its role as storage.

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 you discover something worth carrying forward') and pairs with recall/forget for retrieval and deletion, providing clear decision context.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive hints. The description adds substantial behavioral context: it reveals the tool 'cascades through several lookup endpoints internally,' labels each identifier with its source, explicitly reports unresolved identifiers under `unresolved` rather than omitting them, and degrades gracefully if GLEIF or OpenFIGI are unavailable. This goes well beyond the structured hints and gives the agent predictable expectations for edge cases.

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

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

The description is long but well-structured: opening example phrases, a concise purpose statement, a usage directive, and a detailed breakdown of supported types and their outputs. Each sentence provides essential functional information—resolved identifiers, source labels, unresolved handling, and fallback behavior—with no redundancy or filler. This is appropriately sized for a tool of this 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?

With no output schema, the description takes on the full burden of explaining return values. It does so clearly: for companies, it lists CIK, ticker, company_name, LEI, FIGI, and parent/child ownership; for drugs, it describes RxCUI, ingredient, brand, and a citation. It also covers failure modes (unresolved identifiers, GLEIF/OpenFIGI unavailability). Given the tool's internal complexity, this description provides all the context an agent needs.

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 both parameters with examples, but the description enriches them significantly. For `type`, it details what each enum value returns (company: CIK/ticker/LEI/FIGI; drug: RxCUI/ingredient/brand). For `value`, it specifies accepted formats (ticker, CIK, company name; brand or generic drug name) and provides concrete examples like 'AAPL', '0000320193', and 'ozempic'. This adds meaning well 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 starts with concrete example queries ('What's the ticker for...', 'find the CIK for...') and immediately states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This specific verb+resource framing clearly sets it apart from siblings like entity_profile or compare_entities, and the 'Use FIRST' directive reinforces its role as the initial name-to-ID step.

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 an explicit positive usage directive: 'Use FIRST whenever you have a name but need an ID.' It also explains the supported entity types and the kind of inputs accepted. However, it does not explicitly mention when NOT to use it (e.g., 'if you already have an ID, use entity_profile instead') nor does it name alternative tools, so it lacks the full when-not/alternatives detail required for 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 provide strong behavioral cues (readOnlyHint, idempotentHint, destructiveHint=false), so the description's additional disclosure of return format (ranked list with score, confidence, signal density) adds moderate value. There is no contradiction and the description does not introduce hidden side effects.

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

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

The description is two sentences: first states the action and output, second provides usage context and an example. Every word is functional, with no redundancy or filler. Ideal conciseness for an agent.

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

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

The description covers the return format (ranked list with score, confidence, signal density) and input constraints (2-8 entities), which is sufficient for a read-only tool with rich annotations. It does not detail error handling, but this is not critical given the annotations and clear usage.

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

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

Schema coverage is 100% (all 4 parameters documented), but the description adds value by explaining that the first entity in the array is treated as the 'subject' for narrative, and that the models parameter defaults to workers-ai if omitted. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them by score, and identifies most/least recognized. It uses a specific verb ('Compare') and resource ('AI visibility across entities'), distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic 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 frames the tool for competitive AI-marketing audits and gives an example question ('does Claude know about us as well as our competitors?'). This provides clear context for when to use it, but does not explicitly exclude alternatives or state when not to use it, leaving some ambiguity with sibling compare_entities.

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

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

The description discloses behavioral details beyond annotations: partial failure mode (bundlephobia timeout, sources_failed list), that it returns both summary and detail blocks, and that it fans out to multiple sources. This adds significant context beyond the readOnlyHint and idempotentHint 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 and front-loaded, but slightly verbose with examples and details. Every sentence adds value, but it could be trimmed slightly without loss of clarity.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the return format (summary block, per-advisory detail, links, alternative versions) and error handling (partial failures, timeout). It is complete for an 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?

With 100% schema description coverage, the baseline is 3. The description adds value by noting that scoped packages are accepted for the 'package' parameter and that 'version' defaults to the latest, providing clarity beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages across deps.dev and bundlephobia. It distinguishes from sibling tools (e.g., deep_research, bet_research) as the only tool specifically for npm package evaluation.

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

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

The description explicitly says when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. It also states the limitation to npm ecosystem v1 and directs users to deps.dev:version for other ecosystems, providing clear when-not-to-use guidance.

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

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

Description adds details beyond annotations: character offsets, similarity scores, embedding model (BGE-base-en), window size (500-char), char cap (200K), truncation flagging. Annotations indicate read-only, idempotent, nondestructive, but description enriches with implementation specifics.

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 core purpose, no fluff. Every sentence adds essential information: use case, return details, pairing, technical specs.

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 thoroughly explains return structure (passages with offsets and scores), performance (500-char windows, BGE embeddings), and limits (200K chars). Complete for agent 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%, so baseline is 3. Description adds value with examples for query ('supply-chain risk', 'drug interactions'), default limit, and max char constraint for text. Enhances understanding beyond 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?

Description clearly states semantic search inside a fetched record, returning passages with offsets and similarity scores. Distinguishes from siblings by specifying when to use (when record too big for prompt) and pairing with ask_pipeworx_grounded.

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

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

Provides explicit context: 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Clearly guides agent on when to invoke.

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

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

The description discloses key behavioral traits beyond annotations: returns new subscription ID, delivery channel limits (SMS 10/day), webhook HMAC signing and auto-disable after 10 failures. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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 efficiently structured: starts with core purpose, then prerequisites, followed by type details and delivery options. While moderately long, each sentence carries useful information; minor redundancy in delivery section.

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

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

Given the tool's moderate complexity (3 params, nested objects, no output schema), the description covers all necessary aspects: prerequisites, type variations, delivery channels with constraints, and behavioral notes. No significant gaps.

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

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

Schema coverage is 100%, but the description adds significant context: explains type-specific param structures (e.g., sec_8k items codes, polymarket_edge topics), delivery constraints (phone verification, webhook secret). Adds meaning beyond enum names.

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

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

The description clearly states the action (Create), the object (proactive monitoring subscription), and the data source (live-data event stream). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by specifying creation of new 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?

The description provides explicit prerequisites (requires Pipeworx OAuth account) and lists supported subscription types with examples, guiding correct usage. It implicitly advises against using this tool for anonymous/BYO accounts. Could be improved by explicitly stating 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds meaningful behavioral context: the tool returns category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog. 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?

Front-loaded with example user queries, then a clear description of return value, then usage. Slightly verbose but each sentence contributes information. Well-structured for quick scanning.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to use it (first tool to call). This is complete for an onboarding tool with simple input.

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 one optional parameter. The description goes beyond the schema by listing possible topic values ('finance', 'pharma', etc.) and explaining that omission gives a cross-category spread. This adds clear semantic value.

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

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

The description starts with example user queries ('What can I ask Pipeworx?') and clearly states the purpose: the onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings by emphasizing that it provides exact tool + argument shapes and is meant to be used first.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic vs. no arguments. This clearly tells the agent when and how to invoke the tool.

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

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

Adds value beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability via 'recent_alerts'. Annotations already indicate non-destructive, idempotent mutation; description confirms and expands. 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, 20 words. Front-loaded with action and purpose. No redundancy. Every sentence is necessary 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 single parameter, no output schema, and simple behavior, the description fully covers ownership, state change, and relation to 'recent_alerts'. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with description for 'id' parameter. Description adds context that id is 'returned by subscribe', which is helpful but not extensive. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes from siblings by mentioning ownership enforcement and deactivation vs deletion, and references 'recent_alerts' for historical events, providing specific scope.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Mentions deactivation (not deletion) and links to 'recent_alerts' for historical data, implying when not to use. Does not explicitly name sibling alternatives, but context is sufficient.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds significant behavioral nuance: it details the two verification pipelines, the meaning of 'could_not_verify' (check did not happen, not evidence), and the 'unsupported' state. This goes well beyond the structured annotations and prevents misinterpretation of negative results.

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

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

The description is long but well-structured, front-loading with natural-language triggers, then usage, behavior, return values, and caveats. It is appropriately sized for the tool's complexity, though slightly verbose with phrases like 'Replaces 4–6 sequential calls' that are nice-to-have rather than essential.

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

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

No output schema exists, but the description fully specifies the verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the citation format, and the meaning of edge cases. It covers both financial and general paths, making it complete for an agent to decide whether to use the tool and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description does not elaborate on claim or tolerance_pct beyond the schema, though it gives example claims and mentions percent-delta math. It adds no new parameter-level meaning 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?

The description clearly identifies this as a natural-language claim verification tool with explicit examples of triggering phrases ('Is it true that…', 'fact check'). It distinguishes from siblings by specifying the dual-path handling of company-financial claims vs all other factual claims, and positions it as a replacement for 4–6 sequential calls.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear context. It also explains the fallback behavior for non-financial claims, but does not explicitly name alternative tools or exclusion scenarios, so it lacks explicit when-not guidance.

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