ureweries

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, so the safety profile is clear. The description adds value by disclosing cost implications: 'you pay Anthropic directly for those calls' and 'free' for Workers AI. It also reveals the output structure and the concept of 'signals' which are not in annotations. However, it doesn't mention rate limits, latency, or whether the tool caches results, but given the strong annotation coverage, the description supplements enough.

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, front-loaded with the core action and output. Each sentence earns its place: action+output, model/cost details, and use cases. No redundant phrases or fluff. The structure flows logically from what it does, to how to configure, to when to use.

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 4 parameters, full schema coverage, and strong annotations, the description is complete enough for an agent to select and invoke correctly. It explains the return format (per-model score/confidence/signals/raw_response + combined view) which is crucial despite the absence of an output schema. It covers model selection, cost, and use cases. There is no missing critical information for a read-only, idempotent probe tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default model and cost for _apiKey, which goes beyond the schema's 'Optional Anthropic API key (sk-ant-...)'. It also clarifies that 'context' is a disambiguator with examples. The description ties models to the scoring output, but doesn't elaborate on the exact format of 'signals' or how score is computed, though that's beyond parameter 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 uses a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the output: a visibility score (0-100) per model. It distinguishes itself from siblings like ask_pipeworx (which likely asks a single LLM for an answer) by focusing on multi-model knowledge probing and scoring, not just querying. The phrase 'what they know about a business / brand / product / topic' and 'per-model {score, confidence, signals, raw_response}' makes the purpose unmistakable.

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

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

The description provides explicit usage contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains model selection trade-offs: default Workers AI Llama-3.3-70b is free, while adding Anthropic requires a BYO key and costs money. It implicitly excludes when not to use (e.g., when you just need a direct answer from a single model, use ask_pipeworx). The clarity of model dependencies (_apiKey needed only for anthropic) is strong guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is well-characterized as a safe, non-destructive lookup. The description adds value by disclosing that it returns 'stable pipeworx:// citation URIs' and that it 'routes the question to the right one of 5,563 tools'—transparency about how it works. A slight deduction because it doesn't mention any rate limits or potential latency for complex queries, though the context signals show no such issues.

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 most critical directive ('PREFER OVER WEB SEARCH'), then explains what it does, provides concrete usage examples, and finally indicates when to use alternatives. Every sentence earns its place, and the structure flows logically from recommendation to scope to examples to escalation guidance. There is no redundancy or filler.

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

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

Given the tool's complexity (6 parameters, 1 required, no output schema, low sibling count), the description is thorough: it explains the tool's purpose, scope, usage guidelines, alternatives, and output format (citation URIs). With no output schema, the description compensates by stating it returns 'structured answer' with specific URIs. No gaps are evident.

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 value by explaining the purpose of the 'question' parameter ('Your question or request in natural language') and listing aliases, but it does not clarify expected input format beyond natural language, nor provide constraints like max length. Since the schema already documents all six parameters and their aliases, the description adds marginal extra context.

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

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

The description clearly states 'PREFER OVER WEB SEARCH' and enumerates specific domains (SEC filings, FDA, FRED/BLS, etc.), establishing a specific verb ('routes the question to the right one of 5,563 tools') and resource ('authoritative structured data with citations'). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by advising when to step up.

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

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

The description explicitly says when to use this tool ('START HERE for most questions', 'Use whenever the user asks...'), when not to use it ('Step up only when needed...'), and names alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions, and implies web search for breaking news contexts. It also provides numerous concrete examples.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds context about being a full working router despite the beta label, that results are compared for merging decisions, and that no candidate is currently active. This enriches the behavioral understanding 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?

Three sentences pack substantial information: purpose, current status, usage instruction, and fallback. The date-specific example ('2026-07-26') adds precision but could be trimmed. Mostly efficient, front-loaded with core identity.

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

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

Covers all critical aspects: what it is (beta router), how it differs from stable, current active status, how to use it, and that it's fully functional. Without an output schema, no return value explanation is needed. Complete for informed tool selection.

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 alias (q, text, input, query, prompt) described. The description merely states 'same arguments' without adding new semantics. Since the schema already does the work, 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 it is a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools and arguments, used for testing candidate routing improvements. It distinguishes itself from the stable ask_pipeworx and sibling ask_pipeworx_grounded.

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

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

Explicitly advises 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It notes when no candidate is active it matches exactly, but does not explicitly list when not to use or provide alternative tool names.

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 by detailing the exact return shape on success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost, none of which is captured by the annotations. This is rich, non-obvious 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 dense but every sentence earns its place: it states the mode, explains the routing mechanism, describes the return contract, enumerates refusal reasons, lists use cases, and includes a cost tradeoff. The structure flows logically from purpose to invocation to usage guidance. No redundancy or filler.

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

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

This is a complex tool with no output schema, but the description thoroughly explains return values, refusal behavior, and the cost/usage tradeoff. It also situates the tool within its sibling ecosystem (same routing as ask_pipeworx, extra cost). The description is fully self-contained for an agent to decide when and how to invoke 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?

The schema already covers all 6 parameters with descriptions (100% coverage), all being aliases for 'question'. The description adds no parameter-level semantics beyond what the schema provides, which is acceptable. Since the schema does the heavy lifting, a 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 it is a 'Hallucination-resistant answer mode' and explains its function: routes, fetches, and extracts answers using only tool result content. It explicitly distinguishes itself from sibling ask_pipeworx by highlighting the grounded extraction and refusal behavior, leaving no ambiguity about 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?

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear when-not-to-use and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This openly names the sibling tool as the alternative, which is model 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 read-only/idempotent/non-destructive, and the description adds substantial behavioral detail: resolver contract (match_confidence, alternative markets), low-confidence short-circuit suppressing analysis, closed/dead market blocking via status, wide-spread illiquidity flag, cancellation/resolution-rule parsing (e.g., refund_50_50), news fallback behavior (_fallback_attempted), and parent_event extraction. This goes far 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 long but well-structured and front-loaded: purpose and usage in the first two sentences, followed by organized sections (classifiers, examples, response shapes, resolver contract, safety, cancellation rules). Every sentence adds operational value for a complex tool; density is justified, though a slightly tighter organization would earn a 5.

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

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

With no output schema, the description fully carries the burden of explaining return values. It details response shapes (market/analysis/evidence), resolver contract fields, parent_event structure, news fallback fields, safety statuses, and resolution-rule risk. It also covers edge cases (low confidence, closed markets, wide spreads) and even quantifies a recurring rules-loss scenario. Exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the market input format (slug/URL/question text) found in the schema and adds classifier/fan-out examples that illustrate the range of inputs but don't materially clarify individual parameter semantics. Depth and include_raw are already well-documented in 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?

Specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes from sibling Polymarket tools (edges, arbitrage) by describing the fan-out to category-specific data packs and market-vs-model comparison. The 'Use for' list further sharpens the intended 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 for' list with example queries ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') establishes when to invoke the tool. It doesn't name alternative tools or exclusions, but the context is clear enough to guide selection among siblings.

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

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

The annotations already indicate a safe read operation, so the bar is lower. The description adds the return fields (location, type, contact details), but does not discuss pagination, ordering, or data freshness. This is some added context beyond annotations.

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

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

The description is two sentences with clear, front-loaded information. No redundant text.

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

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

For a simple read tool with full schema coverage and an output schema, the description adequately explains functionality and return fields. Minor omissions like default limit behavior are already in the 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 input schema covers 100% of parameters with descriptions for city and limit. The description adds no additional parameter semantics, repeating the city examples but not elaborating on limit behavior.

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 'Find all breweries in a city' with concrete examples, specifying the action and resource. It distinguishes from sibling tools like get_brewery by focusing on city-level listing.

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

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

The description implies usage when you need breweries by city, but does not explicitly explain when to use this over alternatives like search_breweries or get_brewery. No exclusions or comparisons are provided.

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

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

Discloses rich behavioral details beyond annotations: pulls from SEC EDGAR/XBRL for companies (including off-calendar fiscal year handling), FAERS/FDA data for drugs, sorts by primary metric, and returns paired data with citation URIs. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds valuable context about data provenance and output ordering.

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

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

The description is dense but every sentence adds value—trigger phrases, data sources, fiscal year edge case, sorting, and return format. It could be tightened slightly (e.g., the 'ALWAYS PREFER' and 'Replaces 8–15' statements overlap), but remains well-organized and front-loaded with the primary purpose.

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

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

For a 2-parameter tool with no output schema, the description is remarkably complete: it explains inputs (types, value formats), outputs (paired data, citation URIs), sorting behavior, data sources, and edge cases (off-calendar fiscal years). It fully compensates for the missing output schema and stands out among siblings like entity_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?

Schema already covers 100% of parameters, but the description adds significant meaning: it explains what 'type' values pull (10-K metrics vs FAERS counts) and what 'values' arrays expect (tickers/CIKs vs drug names with examples). This goes well beyond the schema's basic enum/item 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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with a specific verb and resource. It distinguishes from siblings by emphasizing it replaces sequential single-pack lookups, and the trigger phrases ('X vs Y', 'which is bigger') make the intent unmistakable.

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

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

Clear when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups' explicitly contrast with alternatives. Type-specific guidance for company vs drug data sources further clarifies scenarios.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds extensive behavioral context: account tiers, parallel execution, gap handling with gap recovery hops, hop fields, citation_uri fetchability, contradictions for certain depths, semantic excerpting of large records, and expected timing (15-90s). No contradictions with annotations.

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

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

The description is dense and front-loaded with the account requirement, which is high-priority. Every sentence adds value, but the depth explanation is partially redundant with the schema description and the paragraph could be better structured for quick scanning (e.g., bullet points for key constraints). Still, it avoids fluff.

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

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

Despite no output schema, the description thoroughly explains the return packet structure: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It addresses timing, citation resolvability, and excerpting behavior. For a complex research tool with 2 well-documented parameters, this is complete.

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

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

The input schema covers both parameters (question, depth) with 100% coverage. The description significantly adds meaning beyond the schema: it explains the enum depth values in terms of facet counts (quick=3, standard=5, thorough=8) and their additional behaviors (gap recovery, contradictions, iterative hops). It also clarifies that the question can be broad/multi-part and decomposition is automatic.

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 1462 STRUCTURED data sources' using parallel decomposition. It distinguishes itself from sibling ask_pipeworx (single lookup vs. research) and explicitly contrasts with open-web search. The verb 'research' plus the concrete resource (structured data sources) provides a specific 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?

Explicitly states when to use (broad/multi-part questions, structured data) and when not to use (breaking news, single lookup, unsigned-in users). Names the alternative tool (ask_pipeworx) for those cases. Also notes account/tier prerequisites and a fallback path. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes 'no second schema lookup needed.' This explains the output format and the tool's efficiency, going beyond the annotations without contradicting them.

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

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

The description is well-structured: first sentence defines purpose, second gives usage context, third explains return value, and fourth provides a strategic directive. Each sentence earns its place, and the long list of domains is informative rather than filler. It is front-loaded with the essential purpose and remains concise despite the rich content.

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 explicitly explains what the tool returns (top-N tools with schemas and examples) and how to use it. The annotations cover safety, and the schema covers parameters. For a tool discovery tool, this description is complete: it provides the necessary context for an agent to invoke it correctly and understand the result format.

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

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

Schema description coverage is 100%, with detailed descriptions for query and limit, including aliases. The description's mention of 'top-N' aligns with the limit parameter but doesn't add new parameter-level detail beyond the schema. Since the schema fully documents all parameters, the description provides no additional semantic value, warranting the baseline score of 3.

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

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

The description clearly states the tool's purpose with a specific verb ('Find tools') and resource (tools by describing data or task). It distinguishes itself from sibling tools by being a meta-tool for discovery, while siblings are domain-specific (e.g., search_breweries, deep_research). The scope of domains listed further clarifies what it covers.

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

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

The description explicitly states when to use the tool ('when you need to browse, search, look up, or discover what tools exist') and provides a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear usage context and a hint about alternatives (other tools that might be selected after discovery).

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds valuable behavioral context: parallel fan-out across sources, specific return fields, patent API sunset with soft-fail, GDELT→GNews fallback, and zero-padded CIK requirement. 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 a single dense paragraph but delivers high information density: query examples, preferred usage, source list, return fields, and caveats. It earns its length for a complex tool, though it could be slightly better structured with bullets or separators. Still, it avoids fluff.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: CIK, recent filings with URIs, fundamentals, patents, news, and LEI. It also covers failure modes and limitations (patents soft-fail, names unsupported). For the tool's complexity, this is complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds further value by specifying example formats ('AAPL' or '0000320193') and reiterating the constraint that names are unsupported, which reinforces the schema description without being redundant. A small deduction because it doesn't explain the 'type' parameter beyond what the schema already says.

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 produces a 'full cross-source profile of a US public company' with specific examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings such as compare_entities and resolve_entity by emphasizing holistic, single-call aggregation and the need to resolve names first.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also provides exclusion guidance: 'names not supported (use resolve_entity first)' and tells which input formats are accepted (ticker/CIK). This gives clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat that. It adds minimal behavioral context beyond the action itself (e.g., no mention of permanence or what happens if the key is missing), but the annotations cover the key safety profile.

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?

Concise and front-loaded with the core purpose, followed by usage guidance and sibling references. Every sentence adds value; 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?

For a simple single-parameter delete operation, the description covers purpose, usage context, and relationship to sibling tools. Annotations provide the destructive and idempotent hints, and there is no output schema expected, so nothing critical is missing.

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

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

Schema coverage is 100%, with the parameter 'key' described as 'Memory key to delete'. The description echoes this without adding deeper semantics about key format, naming conventions, or behavior. Meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'), distinguishing it from sibling tools like remember and recall. It specifically identifies what the tool does with a single parameter.

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 use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, offering guidance on alternatives without needing to list them all.

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

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

Annotations already cover read-only, idempotent, and open-world hints. The description adds valuable behavioral context by explaining the fetch-extract-emit process, the standard markdown output, and the deliverable format (single text blob for site-root). No contradictions with annotations.

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

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

The description is two sentences plus a compact use-case list. It front-loads the core purpose, then explains the process and output without unnecessary detail. 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?

The description explains the output format (single text blob for site-root/llms.txt), the process (fetches, extracts, emits), and the intended use cases. Despite no output schema, an agent has enough context to invoke the tool and understand the result.

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

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

The schema already covers 100% of parameters with descriptions for url and max_links. The description does not add parameter-specific details, but that is not necessary given the schema's completeness. 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 generates a production-ready llms.txt for any URL, with a specific verb (Generate), resource (llms.txt), and output format. It also lists distinct use cases that set it apart from sibling tools like scan_competitor_ai_presence.

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 three concrete use cases: indexing a client's site, drafting llms.txt for a project, and auditing competitor site visibility. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the concrete return fields (name, address, coordinates, etc.), which is useful but does not go beyond what the output schema likely provides. No contradiction occurs.

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

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

The description is a single, well-structured sentence that front-loads the main action and lists the specific return fields. Every word earns its place; no redundancy or filler.

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

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

This is a simple tool with one parameter, detailed schema, comprehensive annotations, and an output schema. The description fully covers what the tool does, what it needs (a UUID), and what it returns, so no critical context is missing.

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

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

The input schema already documents the single parameter 'id' with an example and description at 100% coverage. The description reinforces that it's an Open Brewery DB UUID, but adds no new semantic detail 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 ('Fetch') and resource ('full details for a single brewery'), clearly identifying the tool's scope. It distinguishes itself from siblings like search_breweries or breweries_by_city by focusing on fetching details for a single brewery by UUID.

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

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

The description clearly indicates the tool is used when you have a specific brewery UUID, implying a lookup-by-ID context. However, it does not explicitly mention alternatives such as search_breweries or breweries_by_city for discovery, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the scope (caller's own subscriptions), the default active state, and the specific return fields, providing useful behavior beyond annotations, though it does not discuss pagination or sorting.

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

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

The description is two sentences, front-loaded with the verb and resource, and every sentence earns its place: first states purpose and output, second gives usage guidance. No redundancy.

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

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

For a simple list tool with one optional boolean parameter and no output schema, the description covers the essential aspects: what it lists, the returned fields, and when to use it. The annotations cover safety, so nothing critical is missing.

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

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

The schema already provides a full description for include_inactive (100% coverage), so the description adds no new parameter detail. The baseline of 3 applies because the schema carries the burden, and the description's reference to 'active subscriptions' aligns with the default false behavior.

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 the caller's active subscriptions, specifies the returned fields, and contrasts with sibling tools like subscribe and unsubscribe by mentioning use cases for those actions. This distinguishes it well.

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 says to use this tool to review what you're monitoring before adding more or to find an id to cancel, which names the alternatives (subscribe/unsubscribe) and gives clear context. This is a model example of 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?

The description goes well beyond annotations by disclosing rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token return/read behavior, account conditionality, and the fact that it's free and doesn't count against quota. No contradiction with annotations exists; the write-like nature aligns with readOnlyHint=false.

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

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

The description is lengthy but every sentence serves a purpose, covering scope, usage, behavior, rate limits, and follow-up mechanics. It is front-loaded with the core purpose and maintains a logical flow, though it could be slightly tightened without losing value.

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

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

Given the tool has 4 parameters, a nested context object, and no output schema, the description compensates thoroughly. It explains what to expect (claim_token return), how to follow up, rate limits, eligibility criteria, and the intended content of the message, making the tool fully self-explanatory for an agent.

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

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

Schema description coverage is 100%, providing solid parameter details. The description adds extra semantic context by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...') and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This enriches understanding beyond the schema alone.

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

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

The description clearly states the action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and identifies the specific resource (Pipeworx). It distinguishes from all sibling tools, which are research/data tools, by explicitly limiting use to Pipeworx connection tools and giving concrete use cases (bug, feature/data_gap, praise).

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary 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 mark this as read-only, idempotent, and non-destructive. The description adds valuable context beyond that: data is self-aggregated from a CF analytics-engine, contains no PII, and results are cached for 5 minutes to 1 hour depending on the window. This gives the agent a clear sense of freshness and privacy implications. It doesn't fully describe the output structure, but that is partially covered by the stated output fields (pack, tool, count).

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

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

The description is efficiently structured: a clear opening definition, a parenthetical window list, a numbered list of use cases, and a final sentence on data provenance and caching. Every sentence contributes distinct information without redundancy. It is longer than minimal but earns its length by packing in multiple useful details.

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

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

Given the tool is simple (one optional param, no output schema), the description provides sufficient context for an agent to decide when to call it and what to expect in return. It covers what data is returned (top tools, packs, call volume), the meaning of windows, use cases, and caching behavior. It lacks an explicit example response format, but that is a minor gap and the description's stated output structure (pack, tool, count) mitigates 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?

The single parameter 'window' has full schema coverage (100%) with an enum and a description that already explains the trade-off between shorter and longer windows. The tool description only repeats this in parentheses. The parameter semantics are therefore adequately provided by the schema, and the description adds no meaningful new meaning beyond what is already structured.

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 question and answer: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This clearly states the verb (returns), resource (Pipeworx call data), and scope (recent window, 24h/7d/30d). It distinguishes itself from siblings like discover_tools by focusing on aggregate trending signals rather than listing available 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 three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, and aligning with current agent needs. This offers clear context for when to invoke. However, it does not explicitly name alternative tools to use instead, nor does it state when not to use this tool, keeping it at a 4 rather than 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 only indicate read-only, open-world, idempotent, non-destructive. The description adds critical behavioral details: the fill check pricing mechanism, the warning 'realizable_edge_pp ≤ 0 means... do not trade it', the Jaccard similarity threshold, and the partition placeholder filter. These go far beyond annotation semantics.

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 labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). The opening sentence is front-loaded and clear, though the volume of detail makes it less punchy than a minimal description; every section serves a purpose.

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

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

With no output schema, the description compensates by specifying the response shape: 'opportunities[] (gap_pp, suggested_trade...' and 'partition_check{...}'. It covers all modes, edge cases (placeholder filtering), and follow-up tool guidance, making it sufficiently complete for a complex arbitrage tool.

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

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

Schema provides brief parameter descriptions, but the description enriches them with mode semantics: how each parameter triggers a different scan, examples of event slugs and seed questions, and expected output differences. This adds significant meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes this from siblings by detailing unique modes (trending_scan, event, topic) and explicitly referencing polymarket_fill_risk as an alternative for custom sizing.

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

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

It gives explicit mode selection: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also directs users to 'polymarket_fill_risk' for custom sizing, which serves as an alternative tool 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 the tool read-only, idempotent, open-world, and non-destructive. The description goes far beyond this by disclosing 1-hour KV caching keyed on all knobs, the _diagnostics structure for understanding empty segments, the exclusion of Fed candidates from ranking with rationale, and the 24h-move warning when market movement exceeds the edge. These are substantial behavioral details not inferable from annotations.

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

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

The description is a single dense paragraph with heavy use of acronyms, parentheticals, and nested conditions. It is front-loaded with a clear summary, but the remainder lacks sectioning and is far from concise. Every sentence does add value, but the wall-of-text format hurts 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?

With no output schema, the description must explain return values, and it does so thoroughly: by_segment, fed_candidates/fed_note, and _diagnostics are all described with their purposes. It also explains the model families, the reasoning behind the Fed exclusion, and the caching behavior, making it complete for a complex tool.

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

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

Input schema coverage is 100% with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds context for tradeable-edge knobs and the special behavior of min_partition_leg_kelly, but it mostly reiterates schema information. It contributes no crucial parameter semantics beyond what the schema already provides.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb+resource+scope. The three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) further distinguish it from sibling tools like polymarket_arbitrage by emphasizing model disagreement rather than pure arbitrage.

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

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

The phrase 'Built for "what should I bet on today"' provides a clear use-case trigger, and the tradeable-edge knobs (min_liquidity, max_spread_pp) give conditional guidance on tuning. However, it does not explicitly name alternatives among the sibling tools, so it falls short of a 5.

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

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

Annotations already mark it as read-only/idempotent, but description adds extensive behavioral detail: response schema, snapshot gap meaning, TTL limits, decay calculation method, and signed edge values. No contradictions.

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

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

Long but well-structured with sections for args, response, limits. The motivational sentence about wide edges adds context but could be trimmed. Overall, each section earns its place 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?

For a tool with no output schema, the description thoroughly explains every response field, data caveats (snapshot gaps, TTL), and computation specifics. Very complete for a read-only telemetry tool.

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

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

Schema covers both parameters with descriptions (100% coverage), so baseline is 3. Description restates defaults and adds 'max 30' but no significant new semantics beyond schema.

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

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

Clearly states what it does: edge persistence/decay telemetry from polymarket_edges snapshots, answering how long an edge has existed and if it's shrinking. Differentiates from sibling polymarket_edges by focusing on historical time-series rather than current edges.

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

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

Provides clear context for when to use: when you need to know edge longevity/decay, contrasting fresh vs old wide edges. However, it never explicitly names alternatives or exclusions, leaving implicit that polymarket_edges handles current snapshots.

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 annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds extensive context: it 'walks the ladder,' returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and verdict, interprets size_usd differently per mode, and warns of forced_directional_risk and partial basket fills. This fully discloses behavior beyond the 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 logically structured: a one-line definition, then dedicated SINGLE-MARKET and BASKET sections with return-value enumerations, followed by a stark 'USE THIS' guidance block. Every sentence contributes essential context, and there is 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?

With no output schema, the description fully enumerates return fields for both modes, documents parameter defaults and clamps, and provides workflow context (pre-trade validation after arbitrage/edge signals). It covers all operational aspects an agent needs for correct invocation and interpretation.

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

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

Though schema coverage is 100%, the description enriches every parameter: it explains the one-of requirement for market/event, the side enum semantics in both modes (overround/underround capture), the dual meaning of size_usd (max spend vs target proceeds vs settlement notional), and the default auto behavior for basket side. This goes well beyond the schema's field descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' precisely defining the tool's function as a fill-risk validator. It distinguishes itself from sibling tools like polymarket_arbitrage (edge discovery) and polymarket_edges (trade ideas) by explicitly targeting fill execution quality, and it clearly differentiates its two modes (single-market and basket/partition).

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 directs usage: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (thin books make theoretical overround uncapturable; partial basket fills create unhedged directional risk), giving concrete triggers and alternatives.

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

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

Annotations already declare this as read-only and idempotent, and the description adds extensive behavioral context: response fields like compatibility_warning, temporal_alignment, and skipped_cross_type are explained with concrete examples of non-equivalent bet shapes. It even cautions about when spreads are meaningless, which goes far beyond the annotation hints.

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

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

The description is long but front-loaded with the core purpose and modes, and every major behavior is covered. Some redundancy exists (e.g., the closing warning about pre-mapped topics repeats earlier caution), making it not maximally concise.

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

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

Given the lack of an output schema, the description thoroughly covers the response structure, including leg-by-leg prices, top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. It also explains edge cases like temporal misalignment and non-equivalent bet shapes, making it very complete for a tool of this complexity.

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

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

The input schema already describes all three parameters with 100% coverage. The description adds the notion of two modes, explains that explicit parameters override the topic-mapped side, and clarifies the semantic of topic shortcuts. This is value beyond the schema, but not an enormous amount since the schema is already descriptive.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which specifies the exact action (calculating spread) and resource (two prediction markets). It distinguishes itself from sibling tools by focusing on cross-venue price differences for the same event.

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

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

The description clearly explains two usage modes—topic shortcuts vs explicit tickers—and warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable.' However, it does not explicitly name alternative tools or state when to prefer this over sibling tools, so it stops short of full 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 declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantive context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when key is omitted. This goes beyond what annotations provide and does not contradict them.

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

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

The description is only two sentences, front-loaded with the primary action, and every clause adds value. It avoids redundancy and clearly separates behavior, usage, and scoping.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers purpose, usage context, scoping, and relationships to sibling tools, leaving no important gaps for an agent to use it correctly.

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

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

The input schema covers the single parameter 'key' with 100% schema description coverage, so the baseline is 3. The description adds minor context by explaining that the key is saved via remember and that omitting it lists all keys, but it does not add new syntax or format details beyond the schema.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes the tool from siblings like remember and forget by naming them and stating its complementary role.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also references companion tools (remember, forget), giving clear alternatives and a paired workflow.

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

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

Annotations declare readOnlyHint=true, but the description explicitly describes a mutating side-effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the read-only annotation, making the transparency score 1.

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 sentences, front-loaded with the main purpose, and every sentence adds distinct value: return payload details, filtering, mark_read behavior, and an alternative endpoint. No unnecessary words are present.

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 sufficiently explains the return payload (source, citation_uri, raw event payload), filtering, and mark_read behavior. It also provides an alternative ingestion method. The description covers the tool's complexity well, aside from the annotation contradiction handled separately.

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 meaningful examples and explanations beyond the schema: a concrete type example ('sec_8k'), confirms ISO format for since, and explains the stateful effect of mark_read. This enhances parameter understanding beyond the baseline.

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

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

The description starts with a specific verb and resource ('Pull fired events from your subscription feed') and clearly distinguishes itself from siblings like list_subscriptions and recent_changes. It explains what the tool returns and how it can be filtered.

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

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

It provides clear usage context: 'Polls work fine' and points to an alternative REST endpoint for scripts/dashboards. It also gives concrete filtering examples. However, it does not explicitly state when not to use this tool versus alternatives, so it misses a strong exclusion statement.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), fallback logic (GDELT preferred, GNews on rate-limit/5xx), and a soft-fail due to PatentsView API sunset. It also states the return structure (changes[], total_changes, citation URIs), which is valuable 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 leads with high-signal trigger phrases, then the core purpose, followed by source details and output format. Despite its length, every sentence adds value (fallbacks, soft-fail, return shape, sibling differentiation). 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?

For a multi-source, complex tool with no output schema, the description provides complete invocation context: it explains sources, fallback behavior, time-window formats, output structure, and the alternative tool. An agent would have enough information to select and correctly invoke this tool.

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

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

Schema description coverage is 100%, with each parameter already well-documented (type enum, since format with examples, value ticker/CIK). The description largely repeats this information (e.g., 'since accepts ISO date or relative shorthand') and adds minimal new meaning beyond a minor recommendation already present in the schema. Thus 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 identifies the tool as a 'change feed for a company in the last N days/weeks/months' with concrete trigger phrases like 'What's new with X'. It explicitly distinguishes itself from sibling entity_profile ('Use entity_profile instead when you want the static profile'), making the tool's purpose and scope unmistakable.

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

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

The description provides explicit when-to-use guidance via trigger phrases, and directly names an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also clarifies fallback behavior and source specifics, giving the agent clear conditions 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?

Annotations already indicate idempotency and non-destructive write, but the description adds valuable behavioral context: scoping by identifier and retention policies (persistent for authenticated, 24 hours for anonymous). It also clarifies storage format (key-value pair). This exceeds what annotations alone convey, though it could mention overwrite semantics explicitly.

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

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

The description is four sentences, front-loaded with the main purpose, then use cases, then storage details, then companion tools. Every sentence contributes meaningful information without redundancy.

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

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

For a simple 2-parameter store tool, the description covers purpose, usage timing, persistence, scoping, and related tools. It lacks an output schema but that's not needed for a save operation. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both key and value. The description adds minimal extra parameter semantics but provides illustrative use cases ('a resolved ticker, a target address') that reinforce the value parameter's flexibility. Baseline 3 is appropriate as the 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 uses a specific verb ('Save') and specifies the resource (data as key-value pairs) with a clear purpose (reuse later across sessions). It explicitly differentiates from siblings by mentioning pairing with recall and forget, making the tool's role distinct.

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

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

It provides explicit usage context ('Use when you discover something worth carrying forward') with concrete examples (ticker, address, preference, subject). It also names alternatives and complements directly ('Pair with recall to retrieve later, forget to delete'), clarifying when this tool is appropriate.

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

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

Description adds significant behavioral context beyond annotations: internal cascade through multiple endpoints, graceful degradation on source unavailability, explicit return of unresolved identifiers, and source labeling for each identifier. No contradictions with annotations.

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

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

The description is long but front-loaded with examples and usage directives. Each sentence adds value, though the detailed 'SUPPORTED TYPES' block could be slightly condensed. Overall well-organized for a complex tool.

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

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

For a 2-parameter tool with no output schema, the description covers all necessary context: input interpretation, edge cases (unresolved identifiers, degraded sources), and the explicit behavior of returning canonical identifiers. No gaps.

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

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

With 100% schema description coverage, the description still adds substantial meaning: detailed explanation of each supported type (company, drug), how values like ISIN and CIK are processed, and the enrichment logic (e.g., ISIN-to-LEI mapping). This goes well beyond the schema's brief field descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific verbs like 'resolve' and explicit examples (ticker, CIK, LEI, RxCUI). It distinguishes its role as a prerequisite for other tools by stating 'Use FIRST whenever you have a name but need an ID'.

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 strong usage guidance with example queries and an explicit directive to use this tool first when needing an ID. It implicitly suggests not using it if you already have an ID, but does not explicitly mention alternative tools or when to avoid it, keeping it from a perfect 5.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns ranked list details (score, confidence, signal density) — going 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?

The description is three sentences, each earning its place: main action, mechanism, use case, and return value. No fluff, well front-loaded with the primary purpose.

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

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

Given there is no output schema, the description compensates by explicitly listing return fields (score, confidence, signal density). It also mentions the underlying tool and the use case, making it self-sufficient for an agent to understand the tool's role and output.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds minimal extra parameter meaning: it frames entities as 'your brand + N competitors', but the schema already says the first entry is the subject. No significant added value beyond the schema.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities), and distinguishes itself from siblings like ai_visibility_check by focusing on multi-entity comparison and ranking.

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

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

The description provides clear usage context with 'Useful for competitive AI-marketing audits' and a concrete example. It implies when to use (for multi-entity comparison) but does not explicitly mention when not to use or contrast with similar siblings like compare_entities.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond this: composite fan-out across services, potential 5-30s latency for first bundlephobia measurement, graceful partial failures, and the sources_failed field. 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 moderately long but every sentence earns its place: purpose, use case, return fields, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and structured logically, though slightly dense.

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 (composite call over two external services) and no output schema, the description thoroughly covers what data is returned (summary block, per-advisory detail, links, alternative versions), the ecosystem boundary, and failure behavior. This is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for both parameters, including scoped package handling and version defaulting. The description reinforces these but does not add significant new semantic information about the parameters themselves. Baseline 3 is appropriate since the schema carries the burden.

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 ('should I add this npm package to my project' check) with a clear resource (npm package) and scope (composite of deps.dev and bundlephobia). It clearly distinguishes itself from sibling tools by describing its unique fan-out behavior and the exact type of question it answers.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an explicit alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear exclusion criteria.

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

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

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the safety profile is already established. The description adds return details (location, phone, website, contact details) which is useful context beyond annotations. However, it doesn't disclose additional behaviors like rate limits or result ordering, 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 two short sentences, front-loaded with the core purpose, and contains no filler. It earns a 5.

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

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

Given the simple nature of the tool, the presence of an output schema, and comprehensive annotations, the description is sufficient for an agent to select and invoke the tool correctly. It includes what the tool does and what it returns, so a 5 is warranted.

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 schema descriptions (100% coverage), so the schema already documents 'query' and 'limit'. The description's mention of 'by name' aligns with the query parameter but adds no new semantic information. Thus, baseline 3.

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

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

The description clearly states 'Search for breweries by name', providing a specific verb and resource. The phrase 'by name' differentiates this from sibling tools like 'breweries_by_city' and 'get_brewery', making its purpose distinct.

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

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

The description gives a clear context for when to use the tool: when you need to search for breweries by name. However, it does not explicitly mention alternatives or exclusion criteria, such as 'use breweries_by_city for city-based searches', so it's a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantive behavioral details beyond those: the embedding model (BGE-base-en), similarity function (cosine), windowing strategy (500-char overlapping windows), and hard input cap (200K chars, longer truncated and flagged). It also reveals that results include offsets and scores, which is actionable for an agent needing to verify quotes. No contradiction exists between description and annotations.

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

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

The description is dense but every sentence earns its place. It opens with the core action, then explains the value proposition (saves context), technical specifics (embeddings, windowing, cap), and a pairing suggestion. There is no filler; the structure moves from what → when → how → caveats. Despite its length, it is well-organized and front-loaded with the most critical information.

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

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

Given three parameters, no output schema, and a moderately complex behavior, the description covers all necessary context: input semantics, examples, output characteristics (passages, offsets, scores), performance boundaries (200K cap, truncation flag), and a use-case workflow with ask_pipeworx_grounded. There is no missing critical detail for an agent to decide whether to call and what to expect back. The absence of an output schema is mitigated by the clear description of the return content.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds notable extra semantics: it explains that 'text' means content already pulled (e.g., SEC 10-K body, an article), gives concrete query examples, and clarifies that the return includes character offsets so the agent can verify verbatim quotes. This goes beyond the basic field descriptions, though it doesn't deeply detail the exact JSON shape of the output. A 4 is justified for the added context and examples.

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

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

The description opens with a clear verb-resource pair: 'Semantic search INSIDE a fetched record.' It explicitly details the inputs (text + query) and outputs (passages with offsets and similarity scores), and it distinguishes itself from sibling tools by emphasizing that it operates on already-fetched content rather than fetching or grounding over whole documents. This is a specific, well-differentiated purpose statement.

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 when the record is too big to cram into the prompt' and directly names a complementary alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives an agent clear decision criteria and a workflow context, far exceeding a simple 'use this for search.'

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

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

Beyond the annotations, the description discloses that anonymous/BYO accounts cannot persist subscriptions, that feed delivery is always on and pullable, and that SMS has a 10/day cap and phone verification requirement. These are meaningful constraints not present in the structured data.

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

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

The description is front-loaded with the main action, then uses compact examples and sections for types and delivery. While dense, it avoids fluff and each sentence adds operational value.

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

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

The description covers the tool's purpose, types, delivery options, prerequisites, and output despite the nested schema and no output schema. It gives enough operational context to invoke correctly, especially with the schema filling in webhook details.

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

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

The schema already covers 100% of parameters, so the description adds extra value with concrete examples like 'items:["5.02"] = officer change' and the delivery channel syntax. It aids understanding without replacing 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 'Create' as a specific verb and identifies the resource as 'a proactive monitoring subscription to a live-data event stream'. It also states the return value (subscription id), clearly differentiating from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides context for when to use it: to proactively monitor live-data events, and specifies prerequisites (Pipeworx OAuth account, verified SMS phone). It does not explicitly name alternatives like list_subscriptions, but the use case is clear enough.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses return structure (category-bucketed example questions), the source (live catalog of thousands of tools), and parameter-dependent behavior (full spread vs. focused topic). This adds meaningful behavioral context not present in the annotations.

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

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

The description is somewhat long but every sentence adds value: it lists examples, defines the tool, explains the return format, and gives usage instructions. It front-loads with example queries rather than a direct purpose statement, which is slightly less clear, but overall it is well-organized and not redundant.

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 adequately explains return values (category-bucketed examples with tool + argument shape), usage scenarios, and parameter behavior. It is complete for an onboarding discovery tool with rich annotations, leaving no major gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100% (the optional 'topic' parameter is fully described with allowed values and omit behavior). The description repeats the same info (e.g., pass 'topic' to focus), adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is the onboarding entry point for generating example questions, with a specific verb ('suggest') and resource ('questions'). It distinguishes itself from siblings by explaining it returns category-bucketed examples with exact tool+argument shapes, and explicitly positions itself as the 'FIRST' tool to use when unfamiliar with Pipeworx.

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

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

The description gives explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you') and mentions alternatives (ask_pipeworx, entity_profile, compare_entities). However, it lacks an explicit when-not-to-use statement, so it doesn't fully meet the 5-point criterion of including 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?

Beyond the annotations (which already indicate non-read-only, idempotent, non-destructive), the description adds meaningful behavioral context: ownership enforcement and the fact that the row is deactivated, not deleted, keeping historical events available. This enriches the agent's understanding of side effects.

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

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

The description is two sentences, front-loaded with the primary action and free of unnecessary words. Every sentence adds essential information (what it does, constraints, and the deactivation effect), making it highly concise and well-structured.

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

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

For a single-parameter, no-output-schema tool, the description covers the core aspects: the action, the ownership constraint, and the post-condition (deactivation with preserved history). It does not mention error handling or success response, but given the simplicity, it is sufficiently complete for effective use.

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

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

The input schema already provides a detailed description of the single parameter (id as a subscription uuid from subscribe), and the description only says 'by id', adding no further semantic detail. With 100% schema coverage, the description does not need to compensate, so the 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 action ('Cancel a subscription by id') with a specific verb and resource, and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' through the explicit cancellation purpose and the note about deactivation preserving history for '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?

The description provides clear context for when to use the tool (to cancel a subscription) and includes an important restriction ('you can only cancel your own subscriptions'), which acts as a usage exclusion. It does not explicitly name alternatives, but the purpose is unambiguous.

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

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

Annotations already mark it read-only, open-world, and idempotent; the description adds substantial context: internal pipeline details (SEC EDGAR/XBRL fast path vs. grounded pipeline), return verdict enum, and especially the caller-critical semantics of could_not_verify vs. unsupported. This goes beyond what annotations provide and prevents misuse.

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

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

The description is long but every sentence earns its place: user intents, when-to-use, routing logic, return payload, important error semantics. It's front-loaded with examples and includes a clearly marked caveat. No redundant fluff.

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

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

Despite having no output schema, the description explains the verdict enum, included value and citation, reasoning, and the verification_error field. It covers the two distinct execution paths and their implications, making the tool self-contained for an agent. The high complexity is matched by thorough disclosure.

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 enriches parameter meaning: it explains tolerance_pct's role as an override, gives concrete guidance (1–2 for hallucination detection), and notes the default cap. This is actionable guidance beyond the schema's field descriptions.

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

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

The description explicitly names the tool's verb and target (validate/verify factual claims against authoritative sources) and distinguishes it from siblings by focusing on claim verification rather than open-ended research. The natural-language query examples make the purpose unmistakable.

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

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

It clearly states when to use (whenever the agent must check factual correctness) and gives trigger phrase examples. It also explains the two routing paths (financial vs. other) and notes it replaces 4–6 sequential calls, implying it is the efficient choice. However, it does not explicitly name alternative tools or state 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.