jokes

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds meaningful operational details: the default free model, the requirement to pass `_apiKey` to probe Anthropic, and the fact that the user pays Anthropic directly for those calls. This goes beyond the annotations by disclosing an external dependency and cost implications.

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

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

Three sentences front-loaded with the core function, followed by pricing/behavioral details and use cases. No filler; every clause adds information.

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

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

Covers the tool's purpose, parameters (via schema), behavioral details (default model, BYOK), return structure (per-model score/confidence/signals/raw_response + combined view), and ideal use cases. No output schema exists, so the description correctly fills that gap.

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

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

The input schema already provides 100% coverage with clear descriptions for all parameters (entity, models, _apiKey, context). The description adds no new parameter details beyond the schema, so baseline 3 is appropriate.

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

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

States a specific action ('Probe one or more LLMs') and a clear outcome (score visibility 0-100 per model). The description also specifies return structure and use cases, distinguishing it from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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

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

Explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which gives clear context for when to use. However, it does not explicitly state when not to use it or name alternatives, so it falls short of the top score.

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?

With strong annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=true), the description still adds meaningful context: it discloses routing behavior ('5,529 tools across 1455 verified sources'), argument-filling, citation URIs, tier availability ('works on every tier'), and speed ('one fast call'). No contradiction with annotations. Slight gap: failure behavior and error handling not mentioned.

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 the most critical directive ('PREFER OVER WEB SEARCH') and default-entry positioning. The descriptions is long (~200 words) with multiple paragraphs and examples, but each section earns its place given the tool's role as a universal entry point. Slightly verbose, but the trigger-phrase list and alternative guidance are actionably useful.

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

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

For a complex router tool with no output schema, the description covers the essential ground: input types, data domains, output format ('structured answer with stable pipeworx:// citation URIs'), alternatives, and default positioning. It omits failure/fallback behavior and latency details beyond 'fast,' but adequately equips 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% (6 params, all described, with examples), so baseline is 3. The description adds value by guiding how to formulate the 'question' parameter via trigger phrases ('what is', 'look up', 'get the latest') and concrete examples ('current US unemployment rate', 'Apple's latest 10-K', 'adverse events for ozempic'). This meaningfully helps the agent construct the parameter 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 uses a specific verb+resource pattern: 'Routes the question to the right one of 5,529 tools across 1455 verified sources... returns the structured answer with stable pipeworx:// citation URIs.' It clearly states the tool answers factual questions by routing to underlying data sources and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance is present: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'START HERE for most questions — this is the default entry point.' It names alternatives and when to use them: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' Also addresses the breaking-news case.

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

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

The description goes beyond the readOnlyHint/openWorldHint/idempotentHint annotations by explaining the beta status, live candidate activation, the current no-active-candidate state, and that it is a fully functional router. It also clarifies that it may differ from the stable router only when candidates are active.

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

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

Three sentences, each providing essential context: what it is, the current state, and usage guidance. Although the date and comparison details add slight wordiness, they are relevant and keep the description efficient.

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

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

For a simple one-parameter router, the description fully covers the beta nature, usage, and current behavior. It does not describe the response format, but the 'same response shape' reference to ask_pipeworx and the schema make it sufficient.

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

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

The input schema already documents all parameters fully (100% coverage), including the 'question' field and all aliases. The description does not add further parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly identifies it as the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by explaining the experimental routing improvements and current inactive candidate state.

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

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

It explicitly tells the agent to use it like ask_pipeworx when wanting the newest routing, and contrasts it with the stable router by noting results are compared for merge decisions. It lacks an explicit 'when not to use' statement, but the stable alternative is clearly 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?

While annotations already cover the read-only, idempotent, non-destructive profile, the description adds valuable behavioral context: it returns a structured refusal with specific reasons when data doesn't directly answer, uses only tool-result content, and costs an extra LLM call. These details significantly enhance 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?

The description is information-dense yet well-structured, starting with the core purpose, then routing behavior, return contract, usage guidance, and cost. Every sentence contributes necessary context, and the formatting with code-like return types improves readability.

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

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

Given the tool's complexity (meta-routing, refusal modes, cost implications), the description covers all essential aspects: purpose, behavior, return types, refusal reasons, and trade-offs with alternatives. It even references the sibling tool explicitly, making it self-contained for an agent.

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

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

Schema coverage is 100% and the schema describes the question parameter and aliases clearly. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the tool's function (extracts answers using only tool result content), and explicitly distinguishes from sibling ask_pipeworx by noting the extra LLM call and grounded nature.

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

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

The description provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on...') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), naming the alternative and the cost trade-off. This is exactly what usage guidelines should do.

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 and destructiveHint=false, but the description goes far beyond them. It details fan-out to parallel data packs, response shapes, resolver contract fields, safety blocking for low-confidence matches, market_closed_or_inactive status, illiquid_wide_spread handling, and resolution-rule risk. This is rich, precise behavioral context that annotations alone would not provide.

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

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

The description is long but exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds operational value—no filler. While not short, it is appropriately sized for a complex tool with many behavioral nuances.

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 thoroughly covers input formats, classifier taxonomy, fan-out behavior, response fields, resolver contracts, parent-event extraction, news fallback handling, safety short-circuits, and cancellation rules. It leaves no critical operational gap for an agent to guess.

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 substantial meaning. It explains the 'market' parameter accepts a slug, URL, or question text; clarifies 'depth' quick vs thorough; and details 'include_raw' with size implications (20KB vs 50KB-500KB) and when to use true. This goes well beyond the schema's own descriptions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on evidence retrieval and analysis for a given bet. It also enumerates classifiers and use cases, further anchoring its 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?

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool blocks (low-confidence, closed markets) and what to check before sizing bets. However, it does not explicitly name alternative tools or when to prefer them, only implying this is the go-to for bet research.

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. The description adds valuable behavioral details: company data from SEC EDGAR/XBRL with off-calendar fiscal year handling, drug data from FAERS/FDA, results sorted by primary metric, and return of paired data with citation URIs. This goes well beyond annotation information.

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

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

The description is information-dense but slightly verbose with multiple quote examples and capitalized phrases. Each sentence adds value, and the structure front-loads the core purpose before diving into type-specific details. Minor redundancy in examples ('X vs Y' / 'X versus Y') prevents a perfect score.

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

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

Despite having no output schema, the description fully informs the agent: what data is pulled per type, how results are sorted, what return format is (paired data + citation URIs), and why it's efficient (replaces 8–15 sequential lookups). Combined with the clear schema and annotations, the description is completely adequate for correct invocation.

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

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

Schema covers both parameters fully, but the description adds useful semantics: type values are explained with what metrics are pulled per type, and values clarifies tickers/CIKs for companies vs names for drugs. The extra context about fiscal year handling and sorting enriches parameter understanding.

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 the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific query patterns ('X vs Y', 'rank these companies'). It clearly distinguishes from sibling tools like entity_profile by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and enumerates triggering query types. It also clarifies that type='company' vs type='drug' determines data sources, giving concrete context for selection.

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

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

Even with annotations declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds critical context: account/paid-plan requirements, expected latency (15-90s), output structure with gaps[] and contradictions[], citation_uri fetchability guarantees, and excerpting behavior. It clarifies that 'open world' here means structured sources, not open-web search, and explicitly states it 'never invented' findings. No contradiction with annotations.

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

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

The description is long (~250 words) but densely informative; almost every sentence adds unique value. It is front-loaded with the critical account requirement and alternative-tool pointer, then logically progresses from purpose to usage to behavior. Minor redundancy exists (e.g., 'use ask_pipeworx' appears multiple times), but this is acceptable given 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 the tool's high complexity and no output schema, the description fully compensates: it describes the findings packet structure, gaps[], contradictions[], citation URIs, hop fields, excerpting, and expected timing. It also covers alternative scenarios and account constraints, making the description self-sufficient 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% with detailed descriptions for both parameters, so baseline is 3. The description adds meaningful nuance beyond the schema: it explains that 'question' can be broad/multi-part (decomposition is the point), and elaborates on 'depth' behaviors (quick=3 facets, standard=5 with gap-recovery hop, thorough=8 with iterative leads+contradictions scan). This elevates it above baseline.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in one call, with a specific verb ('research'), resource ('1455 STRUCTURED data sources'), and scope ('broad/multi-part questions'). It explicitly distinguishes from siblings by noting it is 'NOT open-web search' and contrasting usage with ask_pipeworx.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups and breaking/current-news topics, and requires sign-in (with paid tier for 'thorough'). It names exact alternative tools and contexts, satisfying the dimension fully.

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, and non-destructive. The description adds valuable behavioral context: returns top-N tools with full input schemas and curated examples, ready to call directly without a second lookup. This goes beyond mere annotation restatement.

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 in the first sentence and earns its place overall. The long list of example domains is somewhat verbose but helps the agent understand scope. It remains concise at three sentences.

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

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

Given the simple tool (one required query parameter, no output schema), the description is complete: it explains the return format (top-N tools with descriptions and schemas) and the 'ready to call' aspect. No critical missing context.

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

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

Schema coverage is 100%, with each parameter (including aliases) fully documented. The description adds little beyond the schema for parameters, only reinforcing that the query is a natural language description of the task. 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's purpose: 'Find tools by describing the data or task.' It specifies the resource ('tools') and distinguishes itself from siblings by emphasizing discovery across many domains and returning an 'option set' rather than a single answer.

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 is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This clearly tells the agent when to invoke this tool versus other search or data tools.

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

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

Despite strong annotations (read-only, idempotent, open-world), the description adds valuable behavioral context: it fans out across SEC, XBRL, USPTO, news, and GLEIF; notes the USPTO PatentsView API sunset with soft-fail behavior; describes GDELT→GNews fallback; and lists the return structure. This goes well beyond what annotations provide.

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

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

The description is lengthy but every sentence carries important information. It is front-loaded with trigger examples and a clear purpose statement, then moves into technical specifics. No redundant or filler content exists.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers inputs, outputs, fallback behaviors, data sources, and limitations. It even notes the USPTO sunset and GDELT→GNews fallback. This is a complete and self-contained description.

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 documents both parameters with 100% coverage, and the description reinforces this by giving concrete examples ('AAPL', '0000320193') and explaining the zero-padding requirement and the exclusion of names. This adds meaningful semantic detail beyond the raw schema.

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

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

The description clearly states the tool's purpose: building a full cross-source profile of a US public company. It uses a specific verb ('profile'), names the resource ('US public company'), and distinguishes itself from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for names.

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

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

Provides explicit usage cues with trigger phrase examples ('Tell me about X', 'research Acme') and clear guidance on when to prefer this tool over chaining alternatives. Also states when NOT to use it (names unsupported, use resolve_entity first). This is exactly the level of guidance needed.

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 destructive and idempotent, and the description reinforces this with 'Delete' and 'clear sensitive data'. It adds context about when deletion is appropriate, but not many new behavioral details beyond the annotations.

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

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

Two crisp sentences, front-loaded with the purpose, then usage guidance, then related tools. No wasted words; every segment earns its place.

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

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

For a one-parameter destructive tool with clear annotations, the description fully covers what it does, when to use it, and how it relates to siblings. No gaps remain.

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

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

The input schema's single parameter 'key' is fully described as 'Memory key to delete' (100% coverage). The description adds little beyond the schema, only repeating 'by key' and giving an example in the schema itself.

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

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

The description opens with a specific verb (Delete) and a clear resource (previously stored memory by key). It distinguishes this from siblings like remember (write) and recall (read).

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

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

Explicitly tells when to use: stale context, task done, clearing sensitive data. Also pairs with remember and recall, giving relational context that helps the agent choose among the memory tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: it fetches the page, extracts title/description/key links, and emits a standard markdown blob. It does not mention potential limitations (e.g., JS-heavy pages), but the added detail is meaningful for a safe read operation.

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

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

The description is three sentences: clear action, process explanation, and use cases. Every sentence earns its place, and the most important information is front-loaded. 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?

For a tool with two parameters, no output schema, and strong annotations, the description fully covers what the tool does, how it behaves, and when to use it. It also conveys the output format (a text blob ready for site-root) without requiring an output schema. Nothing essential is missing.

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

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

Schema coverage is 100%, with both parameters already having clear descriptions. The tool description adds little beyond what the schema provides, mentioning the default for max_links (25) which is already in the schema. It does not introduce new parameter meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the exact resource (llms.txt), the action (generate/fetch/extract/emit), and provides concrete use cases. It is distinct from all sibling tools, which focus on unrelated domains like research, betting, or jokes.

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

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

The description gives explicit use cases: getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor. It does not explicitly name alternative tools or when not to use this tool, but the context is sufficiently clear and the siblings are unrelated, so there is little 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds a brief note about return contents (joke text, category, content flags), which complements the output schema but does not introduce any contradictions or additional behavioral warnings.

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

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

The description is two sentences long and front-loaded with the core purpose. It avoids unnecessary details and is appropriately sized for a simple random-joke tool.

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

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

Given the simple tool behavior, strong annotations, and the presence of an output schema, the description covers the essential purpose and filters. It lacks explicit usage guidance for related tools, but that is not a completeness issue for a standalone random-joke tool. The invalid category example is a slight detractor but does not make the description incomplete.

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

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

The input schema provides full parameter descriptions (100% coverage), so the baseline is 3. However, the description gives 'general' as an example category, which is not a valid category in the schema (valid ones are Any, Programming, Misc, Dark, Pun, Spooky, Christmas). This misleading example undermines the description's value and could cause incorrect parameter usage.

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

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

The description clearly states the action ('Get a random joke') and the resource (jokes). It also differentiates from sibling tools like search_jokes, get_joke_categories, and get_joke_flags by emphasizing the random selection and optional filters.

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

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

The description provides clear context on when to use the tool (for obtaining a random joke with optional category/type filters). While it does not explicitly mention alternatives or exclusions, the context is sufficient for a simple tool, and it does not mislead about its 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context by noting that the tool lists 'all available' categories and gives examples, but does not disclose additional behavioral traits like rate limits, pagination, or how the output is ordered. This is adequate given the annotations, so a 3 is appropriate.

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

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

The description is a concise two sentences. The first sentence states the action and resource with examples, and the second sentence gives a direct usage pointer to sibling tools. Every word earns its place with no repetition of schema or annotation data.

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

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

This is a simple zero-parameter listing tool with an output schema. The description explains what it returns (available categories) and how to use the results. The output schema handles return-value formatting, so no further detail is needed. Sibling tools like get_joke_flags are not relevant to category listing, and the description is fully complete for its purpose.

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 tool has zero parameters, and schema description coverage is 100% (field is empty). Per the calibration baseline, a parameterless tool receives a 4. The description adds no parameter information because there are no parameters to document, which is acceptable.

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

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

The description opens with a specific verb ('List') and resource ('all available JokeAPI joke categories'), and provides concrete examples (Programming, Misc, Dark, Pun, Spooky, Christmas). It clearly distinguishes from sibling tools by explaining that returned names serve as input to get_joke or search_jokes, which differentiates it from those retrieval 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: before fetching jokes, to obtain valid category names. It explicitly states how to use the output ('Use the returned category names as the category input to get_joke or search_jokes'), but does not mention exclusions or explicitly name alternatives for this list-based tool. That earns a 4 rather than 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, establishing the tool's safety profile. The description adds context about the flag content but does not reveal additional behavioral traits beyond the listing action. This is adequate for a simple enumeration tool.

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

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

The description is two concise sentences with no redundancy. The action and examples are front-loaded, making it immediately parseable.

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 trivial tool with zero parameters, an output schema, and thorough annotations, the description fully covers the purpose and usage. No additional details are needed.

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

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

With zero parameters, the description correctly omits parameter details. The baseline for a no-parameter tool is 4, and there is no schema information to compensate for.

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

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

The description clearly states the tool lists all content filter flags with concrete examples (explicit, political, racist). It uses a specific verb 'List' and resource 'content filter flags', distinguishing it from the sibling get_joke_categories.

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 to understand what filters exclude', providing clear contextual guidance for when to invoke this tool. It does not mention alternatives or exclusions, but the intended use case is well stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds caller scoping and the exact return fields, which is useful but not extensive. 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?

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. No redundant information.

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

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

The tool is simple with one optional parameter and no output schema. The description covers return fields and use cases thoroughly, while annotations provide the safety profile.

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 include_inactive with a description, so schema coverage is 100%. The description's phrase 'active subscriptions' implies the default but does not elaborate on the parameter, adding minimal value beyond the schema.

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

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

The description states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the return fields, clearly distinguishing this from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. It gives clear context but does not name alternative tools or specify when not to use it.

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

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

Despite annotations being all false (no hints), the description discloses valuable behavioral details: the claim_token workflow for follow-up, daily rate limit of 5, free usage with no tool-call quota, and the team's digest/roadmap process. This adds far more context than annotations alone and contradicts nothing.

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

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

The description is longer than average, but every sentence earns its place: it covers purpose, exclusions, workflow, rate limits, and cost. It is well-structured with a clear opening sentence and logical flow, though slightly dense. Not a 5 due to length, but nowhere near 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?

There is no output schema, so the description must explain return behavior. It does state that filing returns a claim_token and that passing that token retrieves resolution status. It also covers rate limits, zero cost, and the exclusions. Minor gap: for standard filings it doesn't explicitly describe whether a full response object or just a token is returned, but the claim_token details largely cover it.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter usage by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and explains the claim_token round-trip usage for reading resolution status. This adds practical semantic guidance 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 opens with a clear verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly differentiates from siblings by restricting feedback to tools served by this Pipeworx connection and mentions specific use cases (bug, feature gap, praise), making it unambiguous.

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

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

It provides explicit when-to-use guidance with concrete triggers ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...') and a clear when-not-to with an alternative action ('if the tool came from a different MCP server... file it with that server instead'). This is model usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h depending on window). This goes well 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 well-structured and front-loaded: first sentence states purpose, second describes output, third enumerates use cases, and fourth provides technical caveats. 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?

The tool is simple (one optional param, no output schema). The description covers what it returns, why it exists, how it is derived, privacy, and freshness. This is sufficient for an agent to decide when to call it and what to expect.

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

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

Schema description coverage is 100%; the window parameter is fully documented with enum values and guidance on interpretation. The description only mentions 'recent window' without adding new information. Since the schema does the heavy lifting, 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses a specific verb ('returns') and identifies the resource (aggregate call data). It distinguishes itself from siblings like discover_tools by focusing on usage trends rather than capability discovery.

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

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

The description lists three explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. It does not provide explicit 'when not to use' or name alternatives, but the context is clear and actionable.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by explaining internal behaviors: monotonicity and partition checks, placeholder filtering, fill check against live CLOB depth, and conditions like realizable_edge_pp ≤ 0 meaning the edge is not in the book. This adds significant behavioral context not available from annotations alone.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and usage, then details quirks. While every sentence adds value, the length is considerable; however, for a complex tool with multiple modes and checks, the structure keeps it navigable. A 4 reflects good organization, not perfect 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?

Despite having no output schema, the description thoroughly explains the response shape (opportunities[] with gap_pp, suggested_trade, etc.), mode-specific outputs (partition_check fields), and behavioral edges (fill check, skipped_low_similarity). The combination of annotations, rich parameter schema, and this description covers the tool's operational context completely for efficient selection and invocation.

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

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

The schema descriptions already cover both parameters (event and topic) with examples and purpose. The tool description adds extra semantic depth by explaining how each mode works ('walks child markets', 'searches related events', 'runs comparator on the union'), which enhances understanding beyond the schema. Since schema coverage is 100%, this extra context earns a score above baseline 3, but it's not a 5 because the schema already provided adequate parameter descriptions.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names specific methods and resources, and distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges by mentioning them as alternatives for custom sizing and 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?

Usage guidance is explicit and thorough. It describes three modes: no-args for trending_scan, 'event' for single-event analysis, and 'topic' for cross-event scanning. It recommends when to use each, provides examples, and explicitly points to polymarket_fill_risk for custom sizing, giving clear when-to-use vs. alternative 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 goes far beyond the readOnlyHint and idempotentHint annotations, disclosing model families, edge calculation details (slippage, Kelly caps), response segment structure, diagnostic fields for empty segments, the 24h move warning, and 1h caching behavior. This gives the agent deep insight into the tool's behavior and limitations.

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 structured into clear segments (models, knobs, response structure). While it is long and contains highly specific details (sport-specific alpha values, exact thresholds), each sentence earns its place by providing operational transparency. It could be trimmed but remains well-organized.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates), the fields carried by each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the knob effects. This gives an agent a complete picture of what to expect and how to interpret results, making the description highly complete for its complexity.

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

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

The input schema already provides detailed descriptions for all 9 parameters (100% coverage), so the baseline is 3. The tool description adds extra context on how knobs like min_partition_leg_kelly interact with partition arbs and why they exist, enriching the schema's semantic meaning.

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

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

The description clearly states the tool 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' with a specific use case: 'what should I bet on today'. It distinguishes itself by detailing three model families and diagnostic output, making it clear this is a discovery tool rather than a generic market lister.

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

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

It explicitly positions the tool for discovering betting opportunities without paging hundreds of markets, and provides usage notes such as the Fed signal caveat and tradeable-edge knobs. However, it does not explicitly name alternative sibling tools or state when not to use this one, so it falls short of the 5-level criteria for explicit exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial non-obvious behavioral context beyond these: snapshots are written on cache-miss (explaining gaps), history depth is bounded by a 60-day TTL, and decay numbers are based on daily closes of edge_pp_net 'net of default slippage, not intraday.' This is exactly the kind of operational nuance that helps an agent reason about 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 longer than the average tool description but is clearly structured into sections (the core question, Args, RESPONSE, LIMITS). Every segment carries useful information: the response format is critical because there is no output schema, and the limits section directly influences interpretation. It could be slightly tightened, but it earns its length.

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

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

With no output schema, the description fully specifies the response structure: tracked[] with the full time-series, first_seen, trend, and decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[] and what gaps mean. It also covers the TTL bound and data source caveats. For a tool of this complexity, the description is remarkably complete.

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

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

The input schema already covers both parameters with descriptions (days: 'Lookback in days (default 14, clamp 2-30)', window: 'Which polymarket_edges window family to read snapshots for: 24hr | 1wk | 1mo (default 1wk)'). The description repeats these arguments nearly verbatim, adding only the phrase 'snapshot family' and a note on the lookback maximum. Since schema coverage is 100%, the baseline is 3; the description adds marginal interpretive value but no new parameter-level semantics.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges (which presumably provides raw current edges) by focusing on historical persistence and decay.

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 a clear use case: 'Answers "how long has this edge existed and is it shrinking?"' and elaborates with examples (fresh vs. 3-week-old edge). It implies when to use it for decay analysis, though it doesn't explicitly name alternative tools or state when not to use it. The contrast with the newest snapshot and expired opportunities gives practical context for interpretation.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds substantial behavioral detail: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is dense and lengthy, but it is front-loaded with the core purpose and uses uppercase mode labels (SINGLE-MARKET, BASKET) to organize behavior. Every sentence carries operational value, though it could be tightened; the high information density slightly sacrifices brevity.

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

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

With no output schema, the description enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict; theoretical_sum vs realizable_sum, capture_ratio, thin_legs[], etc.) and names the dominant failure mode (partial fills/unhedged risk). It fully covers prerequisites, modes, parameters, outputs, and risk 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%, but the description goes far beyond the schema by explaining mode-dependent meanings: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also clarifies the market-or-event requirement and side defaults.

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

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

Opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk versus theoretical edge, and it explicitly names the two modes (single-market and basket).

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing untracked theoretical overround and partial basket fills creating unhedged directional positions, making the tool's recommended context concrete.

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, and non-destructive behavior, and the description adds substantial context beyond that: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. This prepares the agent for non-obvious response states and edge cases.

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

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

The description is longer than average but dense with operational detail: modes, response fields, warning logic, and temporal alignment. It is front-loaded with the core purpose and each subsequent sentence adds a specific behavioral detail, though a few warnings are repeated for emphasis.

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

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

With no output schema, the description carries the full burden of explaining the response shape, including 'spread[].top_spreads_pp', 'compatibility_warning', 'temporal_alignment', and skip counters. It covers edge cases like matched_pairs:0 and both >5 legs, making it complete for a 3-param 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?

The input schema already covers all three parameters with descriptions, and the description adds the two-mode conceptual relationship between topic and explicit overrides. It explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, which adds meaning beyond the individual property 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 clearly identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by naming the exact venues and describing the matching logic, and the two-mode structure plus response fields make the purpose concrete.

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

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

It explains when to use topic shortcuts vs explicit tickers and warns that pre-mapped shortcuts are not necessarily tradeable, saying 'pre-mapped ≠ tradeable'. It also describes when the spread is a real signal versus when non-equivalent bet shapes mean no arb exists, though it doesn't name alternative tools explicitly.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds key behavioral details: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key lists all saved keys. This gives the agent a fuller understanding of the tool's runtime 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?

Three concise sentences, front-loaded with the core action. The second sentence explains a representative use case, and the third covers scoping and sibling tools. No filler or redundant phrases.

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-parameter read-only tool with good annotations, the description is complete. It explains what the tool does, how the optional parameter changes behavior, scope, and relationship to remember/forget, making it sufficient 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?

The schema already fully describes the only parameter (key) with 100% coverage, including the behavior of omitting it. The tool description reinforces this but adds no new semantic information beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: retrieve a saved value via remember, or list all saved keys when key is omitted. It uses a specific verb ('Retrieve') and resource ('value previously saved via remember'), and distinguishes itself from siblings by naming 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?

Explicitly says when to use: to look up context the agent stored earlier without re-deriving it. It also tells how it pairs with remember (save) and forget (delete), providing clear alternative guidance for sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing that mark_read:true will flag returned events as read, affecting future calls, and by noting the feed is persisted. This goes beyond the structured hints without contradicting them.

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

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

Three sentences, front-loaded with the primary action. Each sentence earns its place: what it does, what events contain, filtering/mark_read behavior, and an alternative access method. No fluff or redundancy.

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

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

For a tool with no output schema, the description summarizes return fields (source, citation_uri, raw event payload) and covers key behaviors (filtering, mark_read). It doesn't mention limit or unread_only in prose, but the schema covers those. Slight gap: no explicit pagination or error handling, but not critical.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by giving an example type ('sec_8k') and explaining the interaction between mark_read and subsequent calls ('next call only shows newer ones'). This enriches the parameter understanding beyond the schema.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states what the tool returns (most recent alerts with source, citation_uri, raw payload) and thus distinguishes itself from similar read tools like recent_changes by focusing on subscription alerts.

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

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

It provides contextual guidance by saying 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards, implying this tool is intended for agent interaction and polling. It stops short of explicitly naming sibling tools or exclusion criteria, but the 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?

Beyond annotations (readOnly, idempotent, openWorld, non-destructive), the description reveals critical behavioral details: multi-source fan-out, fallback from GDELT to GNews on rate-limiting or 5xx, and the PatentsView API sunset causing a soft-fail until reactivated. This informs users about potential gaps and source prioritization, which annotations alone do not convey.

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

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

The description is longer than average but information-dense, covering purpose, sources, fallback behavior, parameter formats, return structure, and an alternative tool. It is front-loaded with user intents and avoids filler. Minor deduction for a single dense paragraph that could benefit from clearer sentence separation, but overall every sentence earns its place.

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

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

Given the tool's complexity (multiple sources, fallback logic, data window), the description provides all necessary context: what it returns (structured changes[] grouped by source, total_changes, citation URIs), how to specify the window, and how it differs from entity_profile. Even without an output schema, an agent can invoke it correctly and understand expected 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?

Input schema already covers all three parameters at 100% coverage. The description adds extra semantic value by explaining `since` accepts both ISO dates and relative shorthand with examples, and even suggests typical monitoring values. This goes beyond the schema's basic descriptions while complementing them.

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

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

The description clearly states the tool's function: a change feed for a company in a specified time window, fanning out to SEC EDGAR, news, and USPTO. It explicitly distinguishes itself from the sibling tool entity_profile by directing users to that tool for static profiles, avoiding ambiguity.

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

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

The description provides explicit when-to-use guidance through example queries like "What's new with X" and "updates on Acme," and gives an exclusive alternative: 'Use entity_profile instead when you want the static profile.' It also advises typical monitoring values for the `since` parameter ('Use 30d or 1m'), which helps agents select appropriate inputs.

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

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

The description goes beyond the annotations by explaining memory scoping ('scoped by your identifier') and persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It also clarifies the relationship with recall and forget, providing a richer behavioral picture.

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

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

The description is concise yet informative, with four sentences each serving a distinct purpose: action, usage, technical storage detail, and companion tools. It is front-loaded with the primary function and contains no redundant or filler text.

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

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

Given the tool's simplicity (two params, no output schema), the description provides all necessary context: purpose, usage examples, memory scope, persistence behavior, and related tools. Annotations also convey idempotency and non-destructive nature, so the agent has enough information 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?

The input schema already provides 100% coverage with descriptions for both 'key' and 'value'. The description adds examples of content types (ticker, address, preference, research subject) but does not add additional syntax or format details beyond what the schema already specifies, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later.' It also includes examples of what to store and distinguishes itself from sibling tools by explicitly mentioning complementary tools recall and forget.

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

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

The description provides clear when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and mentions complementary tools ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when not to use this tool, so it lacks 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description goes far beyond by explaining cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of identifier sources, and that unresolved identifiers are listed under `unresolved` rather than omitted. This adds substantial behavioral context.

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

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

The description is long but well-structured, leading with example queries and then providing type-specific details. Every sentence carries informational weight, and the structure makes it scannable. Minor verbosity exists but it's 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?

With no output schema, the description effectively explains key output traits: identifiers are source-labelled, unresolved ones are explicitly listed, and drug lookups return a citation. It covers both supported types and graceful degradation, making the tool's behavior sufficiently predictable for an agent. It stops short of describing the exact response JSON structure, but that's not essential 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?

Both parameters have thorough descriptions in the schema (100% coverage), and the description repeats the same formats (e.g., 'ticker (AAPL), CIK (0000320193), or name') without adding new parameter-level semantics. The added context about enrichment flow relates to output behavior, not input semantics, so the baseline of 3 is appropriate.

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

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

The description lists concrete example queries and states the purpose as 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb+resource and explicitly positions it as the tool to use 'FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also describes supported types and input formats, giving clear context for when to use. However, it does not explicitly state when not to use the tool or name alternative tools for edge cases, so it misses the 'when-not/alternatives' criterion 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 declare read-only and idempotent behavior, but the description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the return structure (score, confidence, signal density), which is absent from an output schema. This goes well beyond what annotations provide.

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

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

The description is three sentences long, each earning its place. The main action is front-loaded, and the use case is clearly stated. No filler or redundancy.

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

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

Given the tool's moderate complexity, four parameters, and absence of an output schema, the description is complete. It explains the input (entities), the process (probe, rank, surface), and the return format (ranked list with score, confidence, signal density). The sibling ai_visibility_check is contextually referenced, which aids understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema, but it does clarify the overall mechanism (probing via ai_visibility_check). The schema already explains entities, models, context, and _apiKey thoroughly, so the description does not need to compensate.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison, and even names the probe mechanism. The example query ('does Claude know about us as well as our competitors?') further clarifies intent.

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 the use case: 'Useful for competitive AI-marketing audits' and provides an example. It implies that this tool is for multiple entities without explicitly saying 'use ai_visibility_check for a single entity,' but the contrast with the sibling tool is clear. It lacks explicit exclusion statements, so not 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 cover safety (readOnly, idempotent, non-destructive), but the description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. It also describes what the return contains, going well beyond structured fields.

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

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

The description is five dense sentences, each earning its place: composite nature, usage triggers, return format, ecosystem scope, and failure behavior. No filler or redundancy.

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

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

Even without an output schema, the description fully enumerates the return structure (summary fields, advisory detail, links, alternative versions) and covers edge cases (timeouts, non-NPM ecosystems). For a multi-source composite tool, this is highly 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% for both parameters (package and version), so the description does not need to add much. It mentions 'version history' and 'recent alternative versions', but does not add new meaning beyond the schema's own descriptions. Baseline 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 composite check for 'should I add this npm package to my project' that fans out to deps.dev and bundlephobia, distinguishing it from sibling tools. It names specific services and data categories, making the 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?

Explicit usage guidance is provided: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives an exclusion and alternative: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the search semantics (keyword-based matching) and that results include categories/types/content flags. It doesn't describe pagination, result limits behavior, or error conditions, but with strong annotation coverage, a 3 is appropriate since the description adds modest extra context.

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

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

The description is a single efficient sentence that states the action and the output content. It's front-loaded with the core purpose. It's slightly terse—could mention safe_mode behavior explicitly in the description—but it is compact and free of 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?

With a strong annotation set (readOnly, openWorld, idempotent) and a rich output schema plus 100% parameter coverage, the description is largely adequate. For a search tool, it reasonably conveys the core purpose and output. It could mention result limits or empty-result behavior, but given the abundant annotation and schema support, this is complete enough.

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% per the context signal, with all four parameters (query, amount, category, safe_mode) having descriptions in the schema. The description itself adds minimal parameter-level detail—it mentions categories and content flags generically but 'content flags' loosely maps to safe_mode. Since the schema handles the heavy lifting, a baseline 3 is correct.

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 searches jokes by keyword or phrase and what returns (matching jokes with categories, types, and content flags). The verb+resource ('Search jokes') is specific and distinguishes it from sibling tools like get_joke (which likely returns a single joke) and get_joke_categories (which lists categories).

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 conveys clear context for when to use—when searching jokes by keyword. It distinguishes implicitly from get_joke (single joke retrieval) through the search semantics. However, it doesn't explicitly state when NOT to use it or name an alternative tool, though given the large sibling list it differentiates well by function.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and a hard cap of 200K chars with truncation flagged. It also explains return payload includes character offsets for verification, adding behavioral depth not present in structured metadata.

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

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

The description is dense but well-organized, front-loading the core purpose and using short clauses. Every sentence adds information (mechanics, limit, pairing), with no filler. It is appropriately sized for the tool's complexity.

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

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

The description covers purpose, usage scenario, technical internals, input limits, and output format (passages with offsets and scores). It also provides an integration point with a sibling tool, making it complete for an agent to invoke correctly without an output schema.

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

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

The schema already provides 100% coverage with descriptions for all three parameters, including default and range for limit. The description adds contextual examples for text ('SEC 10-K body') but does not significantly expand semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: semantic search inside an already-fetched record, returning top passages with offsets and scores. It uses specific verbs ('search inside') and distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded. This is specific and 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 explains when to use: when the record is too big to fit in context, saving context by returning only relevant passages. It also provides a usage pairing with ask_pipeworx_grounded, creating an explicit workflow. This is more than just implied 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 adds significant behavioral context beyond the annotations, including the OAuth requirement, SMS phone verification and 10/day cap, webhook HMAC signing and auto-disable after 10 failures, and the always-on feed. These details align with the annotations (non-read-only, idempotent, non-destructive) without contradiction.

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

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

The description is a dense single paragraph covering purpose, return value, requirements, types, and delivery channels. It is long but every sentence adds value and the main action is front-loaded. Slightly long 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?

For a 3-param tool with nested objects and no output schema, the description covers prerequisites, return value, type-specific examples, and delivery behaviors (email validation implied in schema, SMS verification/limits, webhook security). It is complete enough for an agent to use effectively, though error handling and idempotency consequences are left to annotations.

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 provides 100% coverage with detailed descriptions for every parameter and nested field. The tool description mostly repeats these details (e.g., sec_8k items, delivery channels), adding no new meaning beyond the schema. Thus a baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states "Create a proactive monitoring subscription to a live-data event stream" with a specific verb and resource. It distinguishes from sibling tools like unsubscribe and list_subscriptions by focusing on creation, and supports this with concrete type examples and delivery channel details.

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

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

It explicitly states the prerequisite of a Pipeworx OAuth account and notes the anonymous/BYO limitation, which tells when this tool is appropriate. It also explains how to consume alerts via recent_alerts or the feed URL. However, it does not explicitly name alternative tools for listing or canceling subscriptions, so exclusions are only implicit.

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 and idempotentHint=true, so the safety profile is covered. The description adds that the response contains category-bucketed example questions each with the exact tool + argument shape, drawn from the live catalog, which provides useful context about what to expect from the call 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 substantive paragraph that front-loads user intent, then explains the tool's role, output contents, and calling variants. It is longer than minimal but every sentence contributes useful information, with no 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 low-complexity tool with one optional parameter and no output schema, the description fully covers what the tool returns (category-bucketed examples with tool+argument shapes), how to use it (with/without topic), and when to use it (first when onboarding). No significant gaps remain.

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

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

The single `topic` parameter is fully documented in the schema with a list of values and behavior when omitted ('Omit for a cross-category spread'). The description repeats this constraint with examples ('finance', 'pharma', 'betting') but adds little new meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description opens with common user queries ('What can I ask Pipeworx? ...') and then states 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It clearly distinguishes itself from sibling tools like discover_tools and ask_pipeworx by positioning itself as the starting point for learning about the catalog.

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' This provides explicit when-to-use guidance and names alternatives, satisfying the dimension.

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 meaningful behavioral details beyond the annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This aligns with destructiveHint false and enriches the agent's understanding.

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

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

Two sentences, front-loaded with the action, and every clause adds value (ownership, deactivation, historical events). No wasted words.

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

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

For a simple one-parameter tool with rich annotations, the description covers the purpose, side effects, and data persistence behavior. The mention of recent_alerts provides integration context, and no output schema is needed.

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

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

The schema already provides complete coverage for the single parameter id, with a description ('returned by subscribe'). The tool description adds no further parameter detail, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Cancel a subscription by id') and distinguishes this tool from siblings like subscribe and list_subscriptions. It also clarifies that the row is deactivated rather than deleted, tying to recent_alerts.

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

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

Provides clear context: you cancel by id, ownership is enforced, and historical events remain available. It lacks explicit alternatives, but the scope is well-defined enough for an agent to know when to invoke it.

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

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

Beyond the read-only/idempotent annotations, the description discloses crucial behavioral details: the verdict categories, the meaning of could_not_verify (check did not happen, carries verification_error, must not be shown as evidence), the distinction from unsupported, and the fact that it 'Replaces 4–6 sequential calls.' This is exactly the kind of context an agent needs to correctly interpret results and avoid misusing the tool. 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 relatively long but well-structured: trigger phrases, purpose, routing logic, return values, important caller warning, and efficiency note. Each section serves a distinct purpose. It could be trimmed slightly (e.g., the trigger phrases are somewhat redundant with the title), but the organization is logical and front-loaded with the most essential usage cue ('Use whenever...').

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 thoroughly covers what a caller needs: input types, the two processing paths, the full verdict list, return structure (grounded/structured value with citation and reasoning), and the critical caveat about could_not_verify vs unsupported. This is sufficient for an agent to select and invoke the tool correctly without additional 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% — both 'claim' and 'tolerance_pct' have descriptive schema entries with examples. The tool description adds minimal parameter-specific detail (it mentions 'exact percent-delta math' but doesn't elaborate on the tolerance_pct parameter's semantics beyond what the schema already says). With such high schema coverage, a baseline 3 is appropriate; the description does not meaningfully enhance parameter understanding.

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

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

The description opens with trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and then clearly states the function: 'natural-language claim verification against authoritative sources.' This is a specific verb+resource that directly distinguishes it from sibling tools like ask_pipeworx or compare_entities. It also explains the two verification paths (SEC EDGAR for financial claims, grounded pipeline for others), leaving no ambiguity about what the tool does.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the sub-routing for company-financial vs. other claims, which implies when to expect different behaviors. However, it does not name any alternative tools or explicitly state when NOT to use this tool (e.g., versus ask_pipeworx_grounded), so it's clear but lacks explicit exclusion/alternative references.

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