Ipma Pt

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds critical behavioral details: default free model, requirement for BYO key for Anthropic (with cost implication), per-model return structure, and combined view. No contradictions.

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

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

Three sentences, front-loaded with purpose, then configuration, then return and use cases. No redundant information; 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?

With 4 parameters fully described, annotations covering safety and idempotency, and a clear explanation of the output shape (per-model fields + combined view), the description is complete for an agent to invoke the tool correctly. No output schema is needed given the description.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description enriches by specifying the default model, the need for _apiKey only when probing Anthropic, and the disambiguation role of 'context'. This adds 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 specifies the action ('probe one or more LLMs'), the resource (business/brand/product/topic), and the output (visibility score 0-100 per model). It distinguishes from sibling tools by focusing on AI visibility measurement and scoring, unlike general Q&A or research tools.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. optional behavior. It does not directly compare to siblings but provides enough context for appropriate 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 readOnly, openWorld, idempotent. Description adds context about routing to many tools, returning structured data with citations, and being a fast single call. No contradictions; further details on limitations or rate limits would improve it.

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

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

Description is comprehensive and well-structured with key points front-loaded. While it is somewhat long, every sentence adds value with use cases, examples, and comparisons. Minor redundancy is acceptable given complexity.

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

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

Covers use cases, alternatives, input examples, and output format (structured answer with citations). No output schema but description sufficiently explains what to expect. Could mention exact response structure for completeness.

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

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

Schema coverage is 100% with alias parameters all described as question. Description adds examples and routing behavior but no new detail on parameters beyond what schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool routes questions to one of 5,011 tools across many sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for many data types, provides examples, and gives clear guidance on when to use alternatives: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, and breaking news routes to news feeds.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable behavioral details: it is a working router with experimental improvements, source-preference ranking, and results are compared to the stable router. 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 moderately concise, front-loading the key identity ('Beta version of ask_pipeworx') and packing relevant details. Every sentence contributes value, though it could be slightly shorter without losing meaning.

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

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

Given the annotations covering safety and idempotency, full schema coverage, and no output schema, the description provides all necessary context: purpose, usage, behavioral traits, and sibling differentiation. It is complete for agent invocation.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description does not add additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It specifies the unique behavior (source-preference ranking) and distinguishes from the stable sibling. The purpose is specific and well-defined.

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 instructs usage 'when you want the newest routing' and notes it should be used exactly like ask_pipeworx. It also implies the stable version is the alternative. While it doesn't explicitly say when not to use, the beta label and context provide sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond by detailing the extraction behavior (uses ONLY tool result), return format with explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the extra LLM call cost. 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 extremely concise without loss of essential detail. Key purpose is front-loaded ('Hallucination-resistant answer mode'), mechanism follows, then return format and usage guidelines. Every sentence serves a purpose, no filler.

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

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

Given the tool's complexity (high-stakes, hallucination-resistant) and full schema coverage, the description is complete: it explains behavior, return format (including refusal reasons), usage boundaries, and cost trade-off. No output schema exists, but the return format is fully described. No additional information is needed.

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

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

Schema description coverage is 100% (all parameters documented). The description adds value by listing all aliases (query, q, prompt, text, input) and clarifying that the question is in natural language. This is useful but baseline is 3 due to high coverage, so 4 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the mechanism (same routing as ask_pipeworx but extracts answer only from tool results) and distinguishes itself from sibling tools by making explicit reference to ask_pipeworx for casual lookups.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and recommends preferring ask_pipeworx for casual lookups due to extra cost. It also lists examples (financial verdicts, legal claims, medical lookups, public statements).

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 extensively discloses behaviors beyond annotations: market resolution, classification, fan-out to data packs, response structure, resolver contract details, safety mechanisms (low-confidence match, closed markets, wide spreads), cancellation rules, and fallback fields. 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 comprehensive but verbose, spanning multiple paragraphs with detailed sections. While front-loaded with the main purpose, the length could be streamlined for an agent's efficient consumption.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly explains all return fields (market, analysis, evidence, resolver contract, parent event, news fields, safety flags) and blocking scenarios, leaving no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how the market parameter accepts slugs, URLs, or question text, and clarifies the depth enum and include_raw effects beyond their schema descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It uses a specific verb ('Research'), names the resource ('Polymarket bet'), and provides example use cases ('should I bet on X'). It distinguishes from sibling tools like polymarket_edges by focusing on a single bet's comprehensive data.

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

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

The description explicitly lists use cases and provides fan-out examples for different bet types, guiding when to use the tool. However, it does not explicitly contrast with alternatives or state when not to use it, leaving some ambiguity.

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

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

Annotations already indicate safe, read-only, idempotent. Description adds rich behavioral details: pulls latest 10-K revenue/net income/cash/debt from SEC EDGAR/XBRL with proper fiscal year handling, FAERS adverse-event counts for drugs, results sorted by primary metric, and returns citation URIs. Also quantifies efficiency gain (replaces 8–15 lookups). 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?

Description is densely packed with high-value information but relatively long. Front-loads with query patterns, then covers behavior, then constrains. Every sentence earns its place, though some redundancy exists (e.g., example phrases repeated). Minor trimming could tighten it.

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

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

Given the complexity (two entity types, multiple data sources, citation URIs, no output schema), the description provides comprehensive context. It covers input format, data sources, behavior for each type, sorting, and output structure. An agent can confidently select and 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 already covers both parameters with descriptions (100% coverage). Description adds significant value: explains what data each type pulls (company vs drug), specifies expected input formats (tickers/CIKs vs drug names), and provides examples. Also clarifies constraints (2–5 items, max/min).

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 verb 'compare' and resource 'entities' (companies/drugs). Provides example query phrases ('X vs Y', 'which is bigger') and explicitly distinguishes from sequential single-pack lookups, which are sibling alternatives.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also describes the exact scenarios (comparing 2–5 companies or drugs) and gives concrete example phrases, leaving no ambiguity about when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds substantial behavioral details: parallel tool routing, gap/contradiction handling, excerpting logic, hop fields, citation formats, and expected latency (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?

Despite length, every sentence serves a purpose. Information is front-loaded (account requirement, then purpose, then details). Structure is logical: prerequisites, core behavior, depth modes, caveats, return format, performance expectations. No fluff.

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

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

Given the tool's complexity (1319 sources, 5011 tools, parallel decomposition, 3 depths, no output schema), the description thoroughly covers what to expect: findings with evidence, confidence, source, citation, gaps[], contradictions[], hop field, semantic excerpts, and time ranges. Completely meets the need for an agent to understand invocation and outcomes.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra semantic clarity: depth is explained with facet counts and hop behaviors ('quick=3', 'standard=5 with gap recovery', 'thorough=8 with iterative hop'), and question is described as natural language, multi-part supported.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1319 STRUCTURED data sources', distinct from open-web search. It explicitly contrasts with sibling ask_pipeworx for single lookups or current news, making its purpose unambiguous.

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

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

Provides explicit guidance on when to use (broad/multi-part questions over structured data), when not (breaking news, single lookups), and alternatives (ask_pipeworx). Also notes account requirements and depth tier restrictions.

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, destructiveHint, idempotentHint. Description adds context about output format (schemas with examples, ready to call), but no extra behavioral traits beyond annotations.

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

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

Two sentences plus a list; front-loaded with purpose and usage; every sentence adds value. No wasted words.

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

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

Given 6 parameters and no output schema, description explains what is returned (names, descriptions, schemas with examples) and that results are callable. Sufficiently complete for a discovery tool.

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

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

Schema coverage is 100% and the description doesn't add meaning beyond the schema for parameters like query, limit, aliases. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes from sibling tools by advising to call it first for discovery.

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

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

Explicitly says when to use (browse, search, discover) and provides a clear directive: 'Call this FIRST when you have many tools available and want to see the option set.' Examples enhance clarity.

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 specific return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), notes API sunset (USPTO PatentsView API sunset May 2025), fallback mechanisms (GDELT→GNews), and parameter constraints. All annotations are respected and complemented.

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

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

Well-organized with examples first, then preference guidance, then detailed output. Slightly verbose (multiple examples) but each part adds value; could trim examples without loss.

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 complexity (multiple data sources, fallbacks, parameters), the description fully covers what the tool does, how to use it, and what it returns. No output schema needed given the rich description.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: explains that type is only 'company', value can be ticker or CIK, and explicitly states names are not supported, which is crucial for correct invocation.

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

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

The description uses specific verbs ('profile', 'research', 'brief me on') and resource ('US public company'), and clearly distinguishes from sibling tools by stating it's a cross-source profile in one parallel call, contrasting with chaining single-pack lookups.

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

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

Explicitly states when to prefer this tool over alternatives ('ALWAYS PREFER over chaining single-pack...') and provides exclusion guidance ('Names not supported — use resolve_entity first...').

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but does not disclose any additional behavioral traits like permissions or side effects beyond what annotations cover.

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

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

Two concise sentences with no wasted words. Information is front-loaded with the primary action first.

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 deletion tool with no output schema, the description fully covers purpose, usage context, and pairing with siblings.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description repeats 'by key' but adds no new semantics 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 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by mentioning pairing with them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also notes pairing with remember and recall, providing clear guidance on alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining the extraction process (fetches, extracts title/description/key links) and output format (single text blob), which complements annotations without contradiction.

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

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

Three well-structured sentences with no wasted words. Front-loads the core action and then provides useful context, making it easy to skim.

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 low complexity, two parameters, no output schema, and rich annotations, the description sufficiently covers what the tool does and what it produces. It explains the output format and usage scenario completely.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions max_links but not in more detail than the schema. Baseline 3 is appropriate as description adds little semantic value 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?

The description clearly states it generates a production-ready llms.txt file for any URL, and explains the process of fetching, extracting, and emitting the standard format. It distinguishes from siblings like scan_competitor_ai_presence by specifying the exact output and use cases.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), guiding when to use. However, it does not mention alternatives or when not to use, but the use cases are specific 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?

Adds return value details (temp, precipitation, wind) beyond annotations. Annotations already indicate read-only, non-destructive, and idempotent, which is consistent.

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

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

Two sentences with example, no superfluous words. Front-loaded with purpose. Highly concise and 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 simple one-parameter tool with comprehensive annotations, description fully explains purpose, inputs, and outputs. No missing context.

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

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

Schema coverage 100%, and description adds list of example cities, accent-insensitivity, and reference to ipma_locations for full list, enhancing the schema description.

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

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

Clearly states it's a Portugal weather forecast from IPMA for a Portuguese city, listing specific cities and return fields. Differentiates from siblings like ipma_locations and ipma_sea_forecast.

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 example and acceptable input values. Does not explicitly state when not to use, but context with sibling tools implies use for city forecasts.

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 safe operations; description adds that filter is accent-insensitive substring, 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?

Two sentences plus example, no fluff, front-loaded with 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 no output schema, description covers return fields adequately, and all other aspects are covered.

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

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

With 100% schema coverage, baseline is 3. Description adds 'accent-insensitive substring' detail and example, adding value.

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

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

The description clearly states the tool lists Portuguese cities and islands with globalIdLocal codes and coordinates, distinguishing it from other IPMA tools like forecasts.

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

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

The description provides a usage example and filter behavior, but does not explicitly state when to use vs alternatives; however, context makes it clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context by specifying the data returned (significant wave height, period, direction, SST) and the geographic scope. No contradictions with annotations, and no additional traits (e.g., rate limits) are needed given the nature of the tool.

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

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

The description is concise: two sentences plus an example. It front-loads the purpose and key details without redundancy. Every sentence contributes meaningfully.

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 read-only, non-destructive tool with two optional parameters and no output schema, the description adequately explains output variables and scope. It covers the key information an agent needs to use the tool correctly. Minor gap: no mention of data update frequency or precision, but not critical.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing example values for 'city' (e.g., Sagres, Lisboa) and clarifying the default behavior for 'day' (0= today) and 'city' (omit for all 12 zones). This enhances 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 specifies the tool's function: sea state forecast for the Portuguese coast, listing specific output variables (wave height, period, direction, SST) and coverage (12 zones, including mainland, Madeira, and Azores). This distinguishes it from sibling tools like ipma_forecast (weather) or ipma_seismic.

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

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

The description provides context on appropriate use cases ('Good for surf, sailing, and beach conditions') and includes an example invocation. It does not explicitly state when not to use the tool or mention alternatives, but the sibling list implies other IPMA tools for different data.

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. Description adds behavior beyond annotations: returns specific fields, covers last 30 days, example shows usage. No contradictions.

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

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

Two sentences plus example; front-loaded with core purpose. No unnecessary words.

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

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

No output schema, but description explains return fields. Covers purpose, scope, parameters, example. For a simple retrieval tool with rich annotations and schema, this is sufficiently complete.

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

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

Schema coverage 100% so baseline 3; description adds value by explaining defaults (area='mainland', days=7) and example usage with min_magnitude. This goes beyond schema descriptions.

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

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

Description clearly states it returns recent seismic events from IPMA with specific fields (time, magnitude, depth, etc.) and geographic scope (mainland Portugal+Madeira or Azores). Distinguishes from sibling tools like ipma_forecast, ipma_locations, which cover different data.

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

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

Describes the time range (last ~30 days) and gives an example. Does not explicitly state when to use vs alternatives, but sibling tools are dissimilar in domain (forecast, locations, sea, UV), so context is sufficient.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds value by specifying daily peak-hours UV index for ~3 days with risk level, complementing annotations without contradiction.

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

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

Two sentences with an inline example. Every word adds value; no filler or repetition.

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

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

Given single parameter, no output schema, and clear annotations, description fully informs agent of scope (Portugal cities, ~3 days, risk levels) and usage.

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

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

Schema covers city parameter with description; description adds example (Faro) and notes accent-insensitivity, providing additional clarity 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?

Description clearly states it provides UV index forecast for Portugal from IPMA, listing specific cities and time period. Distinguishes from siblings like ipma_forecast and ipma_sea_forecast by focusing solely on UV.

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?

Description gives explicit examples of cities and implies usage for Portuguese UV forecast. Does not explicitly state when not to use, but clarity is high given the specificity.

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, non-destructive, idempotent behavior. The description adds value by listing the specific return fields, but the core behavioral traits are well-covered by annotations.

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

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

Two concise sentences with no unnecessary words. Every sentence adds value, clearly stating purpose, return fields, and usage guidance.

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 full schema coverage and rich annotations, the description is complete. It covers return fields, usage, and context without needing an output schema.

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

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

Schema coverage is 100% and the parameter description in the schema is sufficient. The description does not add additional semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context and differentiation from siblings.

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

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

Beyond annotations (all false), the description adds rate limits (5 per day), that team reads digests daily, and that feedback affects roadmap. 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?

Every sentence adds value. Front-loaded with purpose, followed by usage, param guidance, and constraints. No wasted words.

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

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

Given 3 params (one nested), no output schema, the description fully covers purpose, usage, parameter details, and behavioral constraints, leaving 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?

Schema coverage is 100%, and description adds value by clarifying enum values for 'type' and instructing to describe in terms of tools/packs rather than pasting user prompts, enriching param understanding.

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

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

The description clearly states the verb 'tell' and resource 'Pipeworx team' about issues (broken, missing, needs to exist). It distinguishes from sibling tools by being a feedback channel, not a data retrieval tool.

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

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

Explicitly lists when to use: for bugs, features/data gaps, praise. Also mentions it's free and doesn't count against quota, providing clear context for selection.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses that the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min–1h depending on window. This adds valuable behavioral context beyond what annotations alone provide.

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

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

The description is concise (three sentences plus bullet points) and front-loaded with the main output. Every sentence serves a purpose without unnecessary filler.

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

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

With one optional parameter and no output schema, the description sufficiently outlines the return structure (top tools, top packs, total call volume) and data source. This 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%. The description adds meaning by explaining the effect of different window values: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the enum values 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?

The description clearly states that the tool returns 'top tools, top packs, and total call volume' over a time window. It distinguishes from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing specifically on trending aggregate signal from CF analytics.

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

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

Three explicit use cases are listed, helping the agent decide when to invoke this tool. It provides context but does not explicitly state when not to use it or mention alternatives, though the use cases are 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?

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds substantial behavioral context: monotonicity checks, partition-sum deviations, semantic anchor, partition filter, fill check against live CLOB depth. No contradictions. Fully discloses tool behavior.

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

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

Well-structured with clear sections for each mode and constraints. While informative, could be slightly more concise; however, every sentence adds necessary detail for proper usage.

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?

Although no output schema exists, the description explains response structure (opportunities[], partition_check, fill check details). Covers key aspects for a complex arbitrage detection tool, but missing explicit return field descriptions for all cases.

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). Description adds value by explaining the difference between event and topic modes, how they work, and recommended usage. Enhances understanding beyond schema alone.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying unique functionality and parameters.

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

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

Provides explicit usage guidance: call with no args for trending scan, 'event' for single-event mode, 'topic' for cross-event scanning. Also advises when not to trade based on fill check. Effectively directs the agent to the appropriate use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing caching (1h at KV level keyed on all knobs), response structure (by_segment with diagnostics), and model internals (e.g., lognormal barrier, GDELT article-volume ratio, partition overround). No contradictions with annotations.

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

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

The description is well-structured with clear sections and bullet points, front-loading the purpose. However, it is verbose with detailed model explanations (e.g., per-sport α values, filtering logic) that could be trimmed for conciseness without losing essential guidance.

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 9 parameters, no output schema, and rich annotations, the description is highly complete. It covers edge cases (Fed bets, empty segment diagnostics), caching behavior, response structure (by_segment with diagnostics and filter_skips), and provides enough context for an agent to understand expected output without an output schema.

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

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

Schema coverage is 100% with all 9 parameters having descriptions. The tool description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly applies to per-leg Kelly, min_kelly does not filter partition arbs) and providing context for defaults (e.g., slippage_pp default of 0.3 based on Polymarket liquidity). This extra context elevates the score above 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 the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement signals and providing three distinct model families.

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 explicates when to use this tool: for discovering tradeable edges without paging hundreds of markets. It details three segments (model-driven, structural arbitrage, concentrated longshot) and provides tradeable-edge knobs (min_liquidity, max_spread_pp) to filter opportunities. It even notes that Fed bets are excluded from ranking, guiding agent behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral detail: explains that edge_pp_net is signed (negative = SELL YES), decay computed on absolute value, trend categories (new, widening, stable, decaying), and the meaning of expired opportunities with lifespan_days. It also warns about snapshot gaps and TTL limits, going well beyond annotations.

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

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

The description is dense but well-organized: it starts with the core purpose, then details the response structure with labeled arrays and fields, and ends with LIMITS. Every sentence adds value. A slight reduction for length, but it is front-loaded and structured effectively for an AI agent.

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

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

Given the tool has no output schema, the description fully compensates by detailing the response structure (tracked, expired, snapshot_dates arrays with all fields) and covering edge cases (gaps, TTL limits, sign convention). With only 2 optional parameters and no nested objects, the description provides complete context for an agent to understand output and limitations.

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 are fully described in the schema (100% coverage). The description adds functional context: 'days' is the lookback (default 14, max 30) and 'window' selects the snapshot family (default '1wk'). While the schema includes similar info, the description ties parameters to the telemetry purpose, helping the agent understand their effect. No contradictions or omissions.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tool 'polymarket_edges' by focusing on time-series analysis rather than raw edges, and explains the behavioral difference between fresh and old edges.

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

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

The description implies usage context by contrasting fresh vs. old edges and explains the output helps decide if an edge is real or stale. It mentions LIMITS (60-day TTL, snapshot gaps) that affect interpretation. It does not explicitly state when not to use or provide direct alternatives, but the sibling context and purpose are clear enough for an agent to infer appropriate use.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk and thin legs. 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 packed with information and uses uppercase markers for modes, making it scannable. It is not overly long, but the single dense paragraph could benefit from slight structuring (e.g., bullet points for return fields) without adding length.

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

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

Despite the lack of an output schema, the description enumerates all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc. for single; theoretical_sum, capture_ratio, thin_legs, forced_directional_risk for basket). It also explains the risk of partial fills and unhedged positions, making the tool's behavior fully comprehensible.

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

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

Schema coverage is 100% and the description elaborates on each parameter: side options with defaults and auto-detection for basket mode, market vs event dispatch, size_usd interpretation (spend vs target proceeds for single-market, settlement notional for basket), and default/clamp values. Adds significant value beyond the schema.

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

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

The description clearly defines the tool's purpose: checking realizable vs. theoretical edge against live CLOB order-book depth. It explicitly distinguishes between single-market and basket modes, and situates itself relative to sibling tools like polymarket_arbitrage and polymarket_edges, making the purpose unambiguous.

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

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

The description provides explicit usage guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable on thin books, partial basket fills create unhedged directional risk).

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds rich behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains when spreads are meaningful or not. 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 thorough and structured with sections, but slightly verbose. It uses bold for key terms and is front-loaded, but could be trimmed without losing meaning.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields like compatibility_warning and temporal_alignment). It covers edge cases and caveats thoroughly.

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, but the description adds value by explaining the relationship between topic and explicit parameters, and that explicit overrides topic. It also provides example values.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on the spread across two venues.

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

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

The description explicitly explains two modes (topic shortcuts and explicit pairings), provides examples, and warns that pre-mapped topics often return compatibility_warning, guiding the agent when to use and when not to trust the results.

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, indicating safe read-only behavior. The description adds value by explaining the scoping mechanism and that omitting the key lists all entries, complementing but not contradicting annotations.

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

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

The description is concise, comprising two efficient sentences. The first sentence states the core action, while the second provides valuable context on usage and scoping, with no superfluous 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 only one optional parameter and no output schema, the description is suitably detailed. It explains both operational modes (retrieve by key vs. list all), use cases, scoping, and reminds of companion tools, leaving no significant gaps.

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

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

With 100% schema coverage, the description adds useful context beyond the schema's property description: it explicitly states 'omit the key argument' to list all keys, clarifying the optional parameter's 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's core function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It provides specific use cases (e.g., user's target ticker, address) and distinguishes from sibling tools 'remember' and 'forget'.

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

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

The description explicitly advises when to use the tool ('to look up context the agent stored earlier') and mentions scoping. It also pairs with related tools ('Pair with remember to save, forget to delete'). However, it lacks explicit 'when not to use' guidance, which keeps it from a perfect score.

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

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

The description honestly discloses that setting mark_read:true flags events as read, which is a write operation. However, the annotations declare readOnlyHint:true, which contradicts this behavior. Per guidelines, score is 1 due to contradiction.

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

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

The description is three well-structured sentences. The purpose is stated immediately, followed by key details and a usage tip. No superfluous words.

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

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

Given the tool has 5 optional parameters, no output schema, and no nested objects, the description covers all key aspects: return fields, parameter usage, polling suitability, and an alternative endpoint. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example values for type ('sec_8k'), explaining the since parameter as ISO timestamp, and clarifying the effect of mark_read. This goes beyond the schema descriptions.

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

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

The description starts with a clear verb 'Pull' and a specific resource 'fired events from your subscription feed', and distinguishes itself by focusing on the most recent alerts with filtering capabilities. No sibling tool directly overlaps.

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

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

The description advises that 'Polls work fine' and points to an alternative endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools or specify when not to use this tool. However, since no sibling does the same job, the guidance is adequate.

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 safety (readOnlyHint, idempotentHint, etc.). Description adds rich behavioral details: parallel calls to multiple sources, fallback logic, soft-fail for USPTO, and return structure.

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?

Single paragraph with no fluff. Front-loaded with purpose and examples. Every sentence adds value.

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

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

Thorough coverage: explains data sources, fallback, edge cases, return format, and alternative tool. Excellent given complexity and no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds examples (ISO vs relative dates, ticker/CIK) and usage tips ('30d' for monitoring), exceeding 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?

Clearly states it provides a change feed for a company aggregating SEC, news, and patents. Distinguishes from sibling entity_profile for static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X') and when-not-to (use entity_profile for static profile). Also explains fallback behavior.

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

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

Description adds scoping by identifier, persistence duration (24hrs for anonymous), and idempotent nature, complementing the annotations which already indicate idempotentHint=true. 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?

Five sentences, each adding value: purpose, usage context, examples, scoping/persistence, companion tools. No extraneous words.

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

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

Given the simple tool with two string parameters and no output schema, the description fully covers purpose, behavior, and usage context.

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

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

Schema coverage is 100% with clear parameter descriptions and examples. The description does not add new semantics beyond stating key-value usage, which is consistent with 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?

Describes saving data for reuse, specifies key-value pair, mentions companion tools (recall, forget), and distinguishes from siblings clearly.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' and gives examples. Mentions alternative tools (recall, forget) for retrieval and deletion.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that each call cascades through multiple endpoints, replaces 2-3 manual lookups, and specifies return values (ticker+CIK for company, RxCUI+ingredient+brand for drug). No contradiction.

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

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

Description is front-loaded with example queries, then purpose, then details. It is concise but covers all necessary information. Slightly long but efficient.

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

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

Given two entity types, multiple input forms, and no output schema, description adequately covers what the tool returns (including citation URIs). Missing pagination or error handling but sufficient for typical use.

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

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

Schema coverage is 100% with basic descriptions. Description adds significant value: for company, lists acceptable inputs (ticker, CIK, or name) and mentions auto-disambiguation; for drug, lists brand or generic. Goes beyond schema.

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

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

Description clearly states the tool resolves a name to an official identifier, provides example queries, and lists supported entity types (company, drug). This distinguishes it from sibling tools like compare_entities or entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Also explains internal cascading logic, implying alternatives are manual or multiple lookups. No direct when-not, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral specifics: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. This adds value beyond annotations without contradiction.

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

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

The description is a single sentence that efficiently conveys purpose, method, and output. The inclusion of a quote example adds slight fluff but does not detract significantly. It is appropriately sized and front-loaded.

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

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

Given the tool's complexity (multi-entity comparison, ranking, probing) and lack of output schema, the description covers the core behavior and return format (ranked list with score, confidence, signal density). However, it does not mention edge cases (e.g., entity count limits) or details on the models parameter beyond 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?

Schema description coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema; it mentions 'your brand + N competitors' but this aligns with the entities parameter description. No additional semantic depth.

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

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

The description clearly states that the tool 'Compare AI visibility across multiple entities side-by-side', specifying the action (compare), resource (AI visibility), and method (probes with ai_visibility_check, ranks by score). It distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

The description provides explicit use context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It implies when to use this tool vs single-entity probe (ai_visibility_check), though it does not explicitly mention alternatives 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?

Adds significant value beyond annotations: describes composite nature, fan-out to deps.dev and bundlephobia, partial failure handling (sources_failed), and latency on first measurement (5-30s). Annotations already indicate readOnly, idempotent, non-destructive; description complements well.

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

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

The description is comprehensive but not overly verbose. It front-loads purpose and usage, and every sentence adds necessary detail. Minor redundancy could be trimmed, but overall 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?

The description is complete for a complex composite tool. It covers return fields, ecosystem limitations, fallback behavior, and latency expectations. No output schema exists, but the description compensates adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds useful nuances: scoped packages accepted for 'package', and version defaults to latest. It also mentions version-related behavior (bundlephobia latency on new versions), which exceeds baseline.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, covering licenses, advisories, and bundle size. It specifies the verb 'scan' and distinguishes from siblings by being a single call that aggregates multiple sources.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes limitations (NPM only in v1, alternatives for other ecosystems) and potential timeout, providing clear context.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds valuable context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and character offsets for verification.

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

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

The description is efficient, front-loading the purpose. Each sentence adds value, though it could be slightly more concise. Overall, it's well-structured for an AI agent.

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

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

Even without an output schema, the description explains return values (passages with offsets and similarity scores) and covers technical details like truncation. It provides sufficient information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds constraints (max 200K chars for text), examples for query ('supply-chain risk'), and default/range for limit (1-20, default 5), enhancing parameter understanding.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record', distinguishing it from siblings like ask_pipeworx_grounded. It specifies the use case of large records and the return of passages with offsets and similarity scores.

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 when 'the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. This provides clear context for when to use the tool versus alternatives.

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

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

Consistent with annotations: non-read-only, non-destructive, idempotent. Discloses authentication requirements, SMS cap, and webhook auto-disable. 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?

Well-organized with clear sections: purpose, account requirement, types, channels. Although lengthy, every sentence adds value and it is front-loaded with the primary action.

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

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

Covers all necessary context: prerequisites, supported types, delivery channels, return value. No output schema, but return is explained. Complete for agent usage.

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

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

Schema coverage is 100%, but description adds significant value: concrete examples for each type, detailed delivery options including webhook signing. Goes beyond the schema's 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 action (Create), the resource (a proactive monitoring subscription), and the outcome (returns new subscription id). It distinguishes 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?

Provides explicit prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel constraints. Does not explicitly contrast with alternatives like recent_alerts, but the guidance is comprehensive.

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

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

Adds context beyond annotations: returns category-bucketed example questions, can be called with no arguments or a topic, drawn from live catalog. Consistent with readOnlyHint and other 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?

Description is front-loaded with intent and uses list-like structure for categories. Slightly long but all information is relevant and no wasted words.

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

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

Complete for a tool with one optional parameter and no output schema. Explains return type (category-bucketed questions with tool shapes) and usage context thoroughly.

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 description adds value by listing example topic values and explaining omission behavior. Already clear from schema, but description enhances it.

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

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

Clearly states the tool returns category-bucketed example questions to help new users understand what to ask. Lists categories and mentions it provides exact tool + argument shapes, distinguishing it from siblings like ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic. Provides example triggers. However, does not explicitly 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.

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

The description adds context beyond annotations: it specifies that subscriptions are deactivated (not deleted), ownership is enforced, and historical events remain accessible. This complements the annotations (destructiveHint=false, idempotentHint=true).

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

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

The description is concise with three sentences, front-loading the action and providing necessary context without any fluff.

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

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

Given the tool's simplicity (one parameter, no output schema) and the presence of annotations, the description fully covers purpose, constraints, side effects, and links to related tools (recent_alerts).

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 complete description of the single parameter 'id'. The description does not add new parameter information, so it 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 ('cancel a subscription by id') and the resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description provides a clear condition ('ownership is enforced') and explains the side effect (deactivation not deletion). However, it does not explicitly state when not to use this tool or compare with alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: it uses different verification pipelines (SEC EDGAR vs grounded), returns a verdict with citation and reasoning, and replaces multiple sequential calls. 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 slightly lengthy but well-structured, with keyword front-loading and clear separation of pipelines. Every sentence adds value; no fluff. A bit more conciseness could push to 5, but it's already effective.

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

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

Despite no output schema, the description fully explains return values (verdict, actual value with citation, reasoning) and the two verification paths. It covers all necessary context for an agent to understand the tool's capabilities and output. Highly complete given 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%, so baseline is 3. The description adds meaning: explains that tolerance_pct overrides implied tolerance, default is implied by wording capped at 5, and provides examples for the claim parameter. This extra context justifies a 4.

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

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

The description uses specific verb-resource pairs ('claim verification', 'fact check') and clearly distinguishes the tool from siblings by detailing two distinct pipelines for financial vs other claims. It lists natural-language query examples, making the purpose immediately clear.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains when to use the structured path vs grounded pipeline, but does not provide explicit alternatives or exclusions among sibling tools, which would elevate to a 5.

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