Imf Portwatch

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds crucial behavioral context: Anthropic probes require a BYO key and incur direct costs, and it details the return structure ({score, confidence, signals, raw_response}). No contradictions.

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

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

The description is efficient: two sentences plus a bullet in the params section. Front-loaded with the core action and outcome. Every sentence contributes meaning without redundancy.

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

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

Given no output schema and high annotation coverage, the description explains all parameters, return structure (per-model + combined), cost implications, and use cases. No missing information for a probe tool.

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

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

Schema covers all 4 parameters with descriptions. The description adds practical value by noting the default model ('Workers AI Llama-3.3-70b free') and clarifying that _apiKey is only needed when probing Anthropic, which goes beyond the schema's description.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs') and output ('visibility 0-100 per model'). It distinguishes itself from sibling tools like ask_pipeworx by focusing on AI visibility scoring across multiple models.

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

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

Provides clear context for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains when to use the _apiKey parameter. However, does not explicitly exclude alternatives among siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds rich context: it routes to 5,529 tools across 1,455 sources, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and handles live news. No contradiction with annotations.

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

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

The description is long but information-dense, front-loading the 'PREFER OVER WEB SEARCH' directive and systematically covering domains, trigger phrases, examples, and alternatives. Some redundancy ('START HERE' repeated with 'default entry point') but 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 no output schema, the description clearly explains the return format (structured answer with stable citation URIs), domain breadth, usage triggers, and escalation paths. This is a complex router tool and the description covers all essential context an agent needs to select and invoke it.

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

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

The input schema has 100% description coverage, documenting the 'question' parameter and all aliases. The tool description itself adds only illustrative examples of queries, not new parameter semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('ask') and resource ('Pipeworx'), clearly defining it as a question-answering router that returns structured answers with stable citation URIs. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research and positioning itself as the default entry point.

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?

Extremely clear guidance: 'PREFER OVER WEB SEARCH', explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and a 'START HERE' directive. It also explains when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions), providing both when-to-use and when-not-to-use.

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

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

Annotations declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context beyond this: candidate routing improvements may be enabled live, no candidate is currently active, and results are compared against the stable router. It also states it 'Falls back to nothing' to confirm full functionality, though the exact impact of an active candidate is not detailed.

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

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

The description is four sentences, each carrying distinct information: identity, current state, usage guidance, and clarification. It is front-loaded with the beta label and contains no wasted words.

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

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

For a complex universal router, the description leverages the sibling relationship by noting it is identical to ask_pipeworx and shares the same response shape. It explains the experimental nature, confirms it is a full working router, and directs usage appropriately. No output schema exists, but the response shape is stated as identical to the stable sibling, making it 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?

The schema documents all 6 parameters (question plus 5 aliases) with 100% coverage, including clear descriptions for each alias. The description only references 'same arguments' without adding new semantics, so a baseline of 3 is appropriate.

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

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

The description explicitly states this is a beta version of ask_pipeworx with the same 5,529 tools, same arguments, and same response shape, and distinguishes it as the experimental edge. It currently matches ask_pipeworx exactly, providing a specific verb+resource with clear sibling differentiation.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies it is not a fallback but a full working router, distinguishing it from the stable sibling. This is explicit when-to-use guidance with the alternative named directly.

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

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

Discloses rich behavioral details beyond the annotations: the exact output shape (answer, evidence, confidence, source, fetched_at, refusal_reason), the explicit refusal mechanism with enumerated reasons, and the constraint that answers are extracted 'using ONLY what the tool result contains.' This adds significant context not covered by readOnlyHint/idempotentHint.

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

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

The description is front-loaded with the core value proposition ('Hallucination-resistant answer mode for high-stakes reads') and packs mechanism, output format, refusal reasons, use cases, and cost trade-off into four sentences. Every sentence earns its place with no redundancy.

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

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

There is no output schema, so the description compensates by fully specifying the success and refusal return structures, including specific refusal_reason enum values. It also covers use cases, the relationship to ask_pipeworx, and the extra-cost consideration, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with all six parameters being question aliases, each described in the schema. The description does not add parameter-specific details beyond the tool's general purpose. Per the rubric, baseline 3 is appropriate when the schema carries the full parameter documentation burden.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads.' It specifies the verb (extracts answer) and resource (tool results from 5,529 tools across 1,455 sources), and differentiates from sibling ask_pipeworx by noting the same routing but with a strict grounding mechanism. This immediately distinguishes it from the siblings.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also says 'prefer ask_pipeworx for casual lookups' and explains the extra LLM call cost, giving clear guidance relative to the alternative.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: fan-out logic, example fan-outs for different classifiers, response shapes, evidence fields, safety mechanisms (low-confidence short-circuit, closed markets), resolution rule risk, and explanations of fields like cancellation_rule and tradeability. This goes far beyond the annotations.

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

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

The description is very long (over 600 words) and contains extensive detail. While well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), it is not concise. Some information could be streamlined, though the complexity may justify the length.

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

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

Given the tool's complexity (classifiers, fan-out patterns, response shapes, edge cases), the description is highly complete. It covers inputs, behavior, outputs (including evidence structure), safety mechanisms, and cancellation rule risk. Since there is no output schema, the description compensates fully by detailing return values and field semantics.

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

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

The input schema covers all 3 parameters with 100% description coverage. The description adds significant meaning: it explains how to pass market (slug, URL, text), what depth modes mean, and when to set include_raw. It provides concrete examples and clarifies default behavior, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists specific use cases like 'should I bet on X.' The tool distinguishes itself from siblings by focusing on single bet research, while siblings cover arbitrage, edges, etc.

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 guidance: 'Use for...' with examples, and advises inspecting market_match_confidence before trusting analysis. It also covers blocking conditions (low-confidence, closed markets). However, it does not explicitly state when to use alternatives, but the context is clear.

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

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

Annotations already declare the tool read-only, non-destructive, idempotent. Description adds data source (IMF PortWatch), multi-day lag, and freshness reporting, providing useful context beyond annotations.

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

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

Description is detailed yet concise, front-loads purpose, then explains returns, constraints, 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?

Despite no output schema, the description fully describes return fields, sorting, and constraints. It 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 covers both parameters with descriptions (100% coverage). Description expands with acceptable name aliases and examples, adding value beyond the schema.

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

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

The description clearly states the tool compares 2-6 chokepoints side by side and ranks by deviation from baseline. It answers specific questions and distinguishes from siblings like chokepoint_daily_traffic.

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 examples and indicates when to use (spot anomalous chokepoint). It does not explicitly exclude alternatives, but the context is clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: results are ordered most-recent-first, include per-cargo-type breakdowns, and accept both friendly names and portid formats. This significantly enhances the agent's understanding of what to expect.

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 four sentences each serving a clear purpose: what it does, output characteristics, example queries, and input format. It is slightly dense but not overly verbose, striking a good balance.

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 presence of an output schema, the description does not need to enumerate return fields. It already covers purpose, output ordering, aggregation level, input flexibility, and realistic use cases, making it complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers both parameters with 100% description coverage. The description adds concrete examples of valid chokepoint values (suez, hormuz, chokepoint1..8), which goes beyond the schema's generic phrasing and helps the agent formulate correct inputs.

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

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

The description clearly states the tool returns daily vessel counts and deadweight tonnage for a specific chokepoint, with time series ordering and cargo-type breakdown. This distinguishes it from sibling tools like chokepoint_compare or chokepoint_status by focusing on single-chokepoint daily traffic 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 provides explicit example use cases (e.g., 'is Suez traffic back to normal after the Houthi attacks', 'Hormuz throughput vs 30d average'), making the intended context clear. However, it does not explicitly mention alternative tools or negative use cases, so it falls short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the nature of the data (annual statistics) and that it is not live, which supplements the annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with the tool's primary function, and every sentence adds value with no redundancy or fluff.

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

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

Given no parameters and no output schema, the description covers all necessary information: what chokepoints are tracked, what data is returned (annual counts, traffic mix, top industries), and how to get live data via a sibling tool. It is complete for decision-making.

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

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

The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter details; it already provides full context for the tool's operation. Baseline for 0 parameters is 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 explicitly states it lists the 8 major maritime chokepoints with annual vessel counts, traffic mix, and top industries. It also distinguishes itself from the sibling tool chokepoint_daily_traffic by noting that for live daily throughput, that tool should be used.

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

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

The description provides clear guidance: 'Use to discover what a chokepoint normally carries' and explicitly directs to an alternative tool for live data, leaving no ambiguity about when to use this tool.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds data source (IMF PortWatch with multi-day lag), freshness_note, and lists exact return fields. No contradictions.

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

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

Long but well-structured: front-loaded purpose, then details, then examples. Each sentence provides value. Could be slightly tighter but still concise for the information density.

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, so description fully explains return fields (vessel counts, DWT, data_lag, baseline stats, per-type deviation, min/max). Also covers source and lag. Complete for a read-only 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% so baseline is 3. Description adds alias examples, default/range for baseline_days, and explains the trailing window. Provides useful examples 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 tool returns chokepoint traffic status compared to a baseline, distinguishing it from siblings like chokepoint_compare. It includes specific verbs ('answers') and examples of queries.

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?

Example queries like 'is shipping through the Strait of Hormuz down' show when to use. However, it does not explicitly state when not to use or mention alternatives among siblings.

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

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

Annotations already declare readOnly and idempotent behavior. Description adds valuable context: data sources per type (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, and sorting by primary metric. No contradiction.

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

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

Front-loaded with example natural-language triggers. Contains multiple pieces of information (use cases, data sources, sorting, citation URIs) in a dense but readable format. Could trim some examples but overall 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?

No output schema, but description covers return format ('paired data + pipeworx:// citation URIs') and sorting. Explains data sources for both entity types. With 2 required params and good annotations, description is sufficient for safe 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% (baseline 3). Description adds that 'for company: tickers/CIKs' and 'for drug: names', which slightly enriches enum descriptions. Mostly restates schema; no deep parameter guidance beyond aliases.

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

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

Clear verb+resource: 'side-by-side comparison of 2–5 companies or drugs'. Distinguishes from sequential single-pack lookups by explicitly stating preference. Lists example queries (e.g., 'which is bigger / better').

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides concrete use cases (e.g., 'rank these companies', 'head to head'). Does not specify when not to use, but context is strong enough for correct 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 the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: account/paid-plan requirements, latency expectations (15-60s, ~90s for thorough), gap[] behavior, contradictions[] for standard/thorough depth, guaranteed-fetchable citation_uri, and semantic excerpting of large records. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with the most critical access requirement, then methodically covers functionality, use cases, alternatives, depth semantics, citation guarantees, and performance. There is no redundancy or filler.

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

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

With no output schema, the description fully explains the findings packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers access requirements, latency, and when to choose alternatives, making the tool fully self-contained for an agent.

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

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

Although the schema already describes both parameters with 100% coverage, the description adds meaningful extra context: depth levels are mapped to specific behaviors (gap recovery, contradiction scan, iterative lead-chasing), and the question parameter is explicitly allowed to be broad/multi-part since decomposition is the point.

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

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

The description clearly identifies the tool as grounded multi-source research over Pipeworx's 1455 structured data sources, explicitly distinguishing it from open-web search and the sibling tool ask_pipeworx. It uses a specific verb ('research') plus resource ('STRUCTURED data sources') and provides concrete examples of broad/multi-part questions.

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

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

The description gives explicit usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also explains the account-required constraint and directs signed-out users to ask_pipeworx.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. The description adds that the tool returns top-N relevant tools with full schemas ready to call, which is extra behavioral context.

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

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

Description is well-structured and front-loaded with the key action 'Find tools by describing the data or task.' It is concise for the amount of information, though slightly long. Every sentence adds value.

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

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

Given no output schema, the description explains the return format: top-N tools with names, descriptions, and schemas with examples. It covers the tool's purpose and output adequately, and the parameter count includes aliases which are well-explained.

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. Description mentions aliases but adds little beyond what's in the schema. The examples provide some context but not deep semantic nuance.

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

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

The description clearly states the tool's purpose: to find tools by describing data or task. It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the discovery tool to call first.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and provides examples of when to use it, such as 'analyze housing market trends' and 'look up FDA drug approvals'.

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 important behavioral traits: it fans out across multiple sources, notes the USPTO PatentsView API sunset in May 2025 (soft-fail), and states that names are not supported. 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?

Description is lengthy but well-structured, starting with examples and a clear recommendation. Every sentence provides value, though some redundancy could be trimmed (e.g., repeating 'full cross-source profile').

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 thoroughly lists all return fields (cik, filings, fundamentals, patents, news, LEI), explains data sources, limitations (patents sunset, names unsupported), and covers edge cases, making it highly complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description reiterates the value parameter usage ('Pass ticker 'AAPL' or zero-padded CIK') and adds context about names not supported, slightly enhancing understanding 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 starts with concrete example queries and clearly states it returns a 'full cross-source profile of a US public company in ONE parallel call.' It lists the resources (SEC, XBRL, news, etc.) and distinguishes itself from 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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and directs users with only a name to 'use resolve_entity first,' providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds 'clear sensitive data', providing extra context about the nature of deletion. No contradiction between description and annotations.

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

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

Extremely concise: two sentences. The first sentence states the action, the second provides usage context and tool pairs. No wasted words, front-loaded with critical information.

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

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

Given a single parameter and no output schema, the description covers the tool's purpose and usage context well. It could mention that deletion is irreversible, but the destructiveHint annotation covers this implicitly. Overall complete for a simple deletion 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 mentions 'by key', but does not add meaningful detail beyond what the schema provides (key is a string, required). The description is adequate but does not enhance understanding of the parameter's role.

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', specifying the action (delete) and resource (memory). It distinguishes itself from sibling tools 'remember' and 'recall' by pairing with them and implying a distinct operation.

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

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

Explicitly provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with 'remember' and 'recall', offering clear guidance on when to use and 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral details: fetches the page, extracts title/description/key links, emits standard markdown format, and produces a single text blob ready for deployment. 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 with no wasted words. Front-loaded with purpose, then process, then use cases. Excellent structure.

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 clearly states the output format ('single text blob ready to drop at site-root/llms.txt') and mentions the standard markdown format. Could add error behavior but not essential for this simple tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal extra meaning beyond what the schema provides, only implying extraction behavior for the url parameter.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file') with clear context ('for any URL so AI crawlers can index the site cleanly'). It distinguishes itself by being the only tool in the sibling list that generates llms.txt files.

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: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't state when not to use it, the tool is specialized enough that the alternatives are clear from the sibling list.

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 no destructiveness. Description adds the specific return fields, which is valuable context beyond the annotations.

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

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

Two sentences, front-loaded with purpose, and no redundant information. Every sentence is meaningful.

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 and rich annotations, the description covers purpose, usage, return fields, and parameter context. No output schema, but return fields are enumerated.

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 well-described boolean parameter. The description does not elaborate further, but the schema already provides sufficient meaning.

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

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

Description clearly states it lists the caller's active subscriptions and specifies the return fields. While not explicitly differentiating from siblings, the purpose is specific and unambiguous.

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

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

Provides explicit use cases: to review before adding more or to find an ID to cancel. Does not explicitly state when not to use, but the guidance is clear and actionable.

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

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

Annotations are all false (readOnly, openWorld, idempotent, destructive), so the description carries the full burden of behavioral disclosure. It does so thoroughly: filing returns a `claim_token`, the token can be used later to read resolution status, it's rate-limited to 5 per identifier per day, free, and doesn't count against quota. These are meaningful behavioral traits beyond what annotations convey.

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

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

The description is substantial but every sentence earns its place: purpose, triggers, exclusions, message quality, claim_token mechanics, and rate limits. It front-loads the primary action and then flows logically through operational details without redundancy. This is dense but not verbose, and the structure supports comprehension.

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

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

With no output schema and moderate complexity, the description fills all gaps: it explains return behavior (claim_token), covers edge cases (tools from other MCP servers), provides policy details (rate limits, quota), and advises how to structure the message. It is a complete picture for an agent to select and invoke the tool correctly.

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

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

The input schema already covers all four parameters with descriptions (100% coverage), so the baseline is 3. The description adds value beyond the schema by explaining the `claim_token` round-trip flow ('Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing how to phrase the `message` ('Describe the issue in terms of Pipeworx tools/packs'). This extra context justifies a 4, though it doesn't independently document each parameter's syntax.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then distinguishes itself from sibling research/query tools by enumerating specific feedback categories (bug, feature, data_gap, praise), which makes its unique purpose unmistakable.

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

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

It explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead,' plus guidance on how to phrase feedback and what not to include.

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=false. Description adds that data is derived from CF analytics-engine, no PII, and cached 5min-1h depending on window, providing context beyond annotations.

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

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

Two sentences with three enumerated use cases. Every sentence adds value, no fluff. Front-loaded with the core 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 the tool's simplicity (one optional param, read-only, no output schema), the description is complete: explains what it returns, derivation, no PII, caching, and use cases. 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 for the single parameter 'window' is 100% with enum values and description. The description adds guidance on when to use each window ('shorter windows surface what's hot right now; longer windows show steady-state demand'), adding 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 returns 'top tools, top packs, and total call volume over a recent window', using a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'). It distinguishes from siblings like discover_tools by focusing on trending 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?

Explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Also clarifies window selection: shorter for 'hot right now', longer for 'steady-state demand'.

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. The description adds extensive behavioral details: partition logic, semantic anchor (Jaccard similarity ≥0.30), partition filter (>20% placeholder fraction returns null), fill check against CLOB depth, and rationale for avoiding non-tradable edges. 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 lengthy but well-organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded main purpose. Every sentence adds value, though some technical details (e.g., fill check thresholds) could be slightly shortened 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?

Given the absence of an output schema, the description fully explains the response structure (opportunities array, partition_check, fill check results). It covers edge cases (placeholder filtering, low similarity pairs) and references a sibling tool for custom sizing, making the definition 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 covers 100% of parameters with descriptions. The tool description enriches these by explaining modes, providing example values (e.g., 'fed-decision-may-2026'), and detailing how event vs topic modes differ in behavior. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event) with precise verb-resource combinations, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode (no args for trending, event for specific market, topic for cross-event) and recommends event mode for specific markets. It lacks a clear 'when NOT to use' statement but effectively covers usage context and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavior: caching (1h KV), detailed response segments (by_segment), edge metrics (edge_pp_net, kelly_fraction), 24h move warnings, Fed bets note, and diagnostic fields. No contradictions.

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

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

The description is lengthy and packed with detail. While front-loaded with purpose, the exhaustive breakdown of model families, response segments, and diagnostic counters could be more concise. However, the complexity justifies the length.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains response structure, edge metrics, filtering knobs, caching, and diagnostic fields, leaving little ambiguity.

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 descriptions are thorough. The tool description repeats some parameter details (e.g., slippage_pp) and explains min_partition_leg_kelly in more depth. Overall, it adds marginal 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 tool's action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement for edge discovery.

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

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

The description states the tool is 'Built for what should I bet on today' and provides knobs like min_liquidity and max_spread_pp to filter tradeable opportunities. It implies use cases but lacks explicit when-not-to-use instructions or direct comparison to 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?

Discloses key behaviors beyond annotations: reads from daily snapshots, decay computed from daily closes (not intraday), history bounded by 60-day TTL, and snapshot gaps explained. No contradiction with readOnlyHint, idempotentHint, etc.

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

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

Front-loaded with purpose, then response fields and limits. Some redundancy (limits paragraph), but overall well-structured. Slightly verbose but necessary for output semantics.

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

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

With no output schema, description fully explains response fields (tracked[], expired[], snapshot_dates[]) and their semantics. Covers all relevant context for a read-only telemetry tool.

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

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

Schema already covers both parameters with descriptions. The tool description adds no new parameter details beyond defaults and examples already present in schema. Baseline score of 3 applies.

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

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

Clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis rather than raw snapshots.

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

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

Provides clear context on when to use (e.g., comparing fresh vs aging edges) and hints at limitations (60-day TTL, snapshot gaps). However, does not explicitly list alternatives or exclusions.

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

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

Annotations (readOnlyHint, etc.) indicate safe read operation. Description adds critical behavioral details: walks the order book ladder, returns verdict (clean/degraded/cannot_fill), forces directional risk, and explains basket mode risks. 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?

Description is dense (≈250 words) but well-structured with uppercase headings for modes. Front-loaded with core function. Every sentence adds value, though slightly verbose for the complexity. Could be trimmed slightly but remains 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?

Given high complexity (two modes, many return fields, no output schema), description fully explains return values, failure modes, and usage context. Covers forced directional risk, thin legs, and max clean notional. No gaps for agent to infer.

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 substantial meaning: explains side default for basket (auto), size_usd interpretation for basket (settlement notional), and clamps (10–1,000,000). Clarifies single-market vs basket parameter usage 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 tool checks realizable vs theoretical edge against live order book depth. Differentiates between single-market and basket modes with specific verbs and resources. Distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on risk assessment before acting on those signals.

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: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains why (theoretical overround not capturable, partial fills cause unhedged directional positions). Specifies required parameters: must provide market or event.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds extensive behavioral context: conditions for compatibility_warning (matched_pairs:0 with skipped_cross_type>0 or both >5 legs), temporal_alignment field meaning, and skipped_cross_type/subtype counters. No contradictions.

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

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

The description is relatively long but well-organized into sections (modes, response, safety fields). Every sentence adds value, but some rephrasing could improve conciseness. Overall front-loaded with core 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, the description thoroughly covers return fields (matched_pairs, spread[], compatibility_warning, temporal_alignment, skipped counters) and explains their meaning. All edge cases (e.g., no temporal alignment) are addressed.

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 each parameter. The description enriches this by explaining the two-mode interaction (topic vs explicit tickers, overrides) and providing concrete examples. It adds meaning beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket, differentiating from siblings like polymarket_arbitrage. It uses specific verbs ('cross-venue spread') and resources ('same resolving question'), and names two distinct modes (topic shortcuts and explicit tickers).

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 tells when to use each mode (topic for 10 pre-mapped macros, explicit tickers for custom pairings) and warns that pre-mapped topics often yield compatibility_warnings, implying when the tool's output is not reliable. It does not explicitly compare to sibling tools but provides sufficient contextual 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 indicate read-only, idempotent, non-destructive. The description adds that it searches a global database of 1,500+ ports and returns specific data fields, which is consistent and provides useful behavioral context beyond annotations.

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

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

Two sentences: first defines action and scope, second lists output and use cases. No wasted words, front-loaded with key 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 the simple read-only search tool with 3 params and no output schema, the description covers purpose, input, output fields, and use cases. Could mention pagination or sorting, but the limit param and explicit output list suffice.

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 param descriptions. The description mentions searching 'by name, country, or ISO3' which aligns with the query and country params, but adds no new param-specific details beyond what the schema already provides.

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

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

The description clearly states the tool searches the PortWatch port database by name, country, or ISO3, and lists specific return fields. This differentiates it from sibling tools like entity_profile or chokepoint tools, which deal with different entities.

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

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

The description explicitly mentions use cases: identifying ports affected by country-level disruptions or finding LOCODE/portid. It does not explicitly state when not to use, but the context is clear enough for an agent to decide.

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

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

Discloses scoping to identifier (anonymous IP, BYO key hash, account ID) and relationship to remember/forget, adding value beyond annotations which already declare readOnlyHint and destructiveHint. 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?

Three sentences with zero wasted words. Front-loaded with core purpose, followed by usage and scoping details. Highly 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 single optional parameter, no output schema, and annotations covering safety, the description provides complete guidance: purpose, usage, scoping, and sibling relationships. No gaps for this complexity level.

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 property description. The description reinforces the optional key behavior and adds context like 'omit the key argument' and pairing with other memory tools, providing slight extra value 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?

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb-resource pairing. It distinguishes from siblings 'remember' and 'forget' by explicitly mentioning pairing, making 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 usage scenario: 'Use to look up context the agent stored earlier' and how to list all keys (omit key argument). Does not include explicit when-not-to-use or alternative tools, but context is clear and sufficient for typical 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?

The description adds behavioral details beyond annotations, such as the mark_read feature affecting subsequent calls and the return format (source, citation_uri, raw payload). Annotations already declare readOnlyHint, idempotentHint, and non-destructive, which are 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?

The description is concise with three well-structured sentences covering purpose, filtering, mark_read behavior, and alternative access. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description explains the return fields and the effect of mark_read. It also addresses polling and alternative access. The tool has 5 optional parameters, and the description covers their use comprehensively for the given complexity.

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

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

The description adds meaning beyond the input schema by explaining how parameters like type and since are used (e.g., 'Filter by type (e.g. sec_8k)') and the effect of mark_read. Schema coverage is 100%, but the description enhances understanding with examples and context.

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

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

The description clearly states 'Pull fired events from your subscription feed,' specifying a verb and resource. It distinguishes from siblings like list_subscriptions and recent_disruptions by focusing on alerts from the subscription feed, but does not explicitly contrast 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?

The description provides usage context such as filtering by type and since, and mentions that polling works fine and the same feed is available via a direct URL for scripts. However, it does not explicitly state when not to use this tool or compare it to sibling tools, 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?

The description fully discloses behavioral traits beyond annotations: parallel call, fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to API sunset, return structure with groups, and since parameter format. Annotations already indicate read-only, idempotent, open-world, and non-destructive, so this adds significant context.

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

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

The description is comprehensive but well-organized, starting with example queries, then tool mechanics, then alternative guidance. Every sentence adds value, though it is somewhat lengthy. The front-loading of examples is 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?

Given the complexity of the tool (multiple sources, fallbacks, return structure), the description covers all essential aspects: input format, output shape, source behavior, and sibling distinction. Without an output schema, the description adequately describes the return value structure.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds extra value by providing typical usage examples for the 'since' parameter ('30d', '1m') and clarifying the value parameter format ('ticker or zero-padded CIK'). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a change feed for a company over a time window, fanning out to multiple sources in one parallel call. It uses specific verbs ('fans out') and distinguishes from the sibling tool entity_profile by explicitly stating when to use the alternative.

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 examples ('what's new', 'latest on Y') and clearly states when not to use this tool: 'Use entity_profile instead when you want the static profile regardless of window.' This clearly guides the agent on tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: lists event types and filter options, which is consistent with annotations. 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 two sentences, front-loaded with key information (event types, attributes, filters, use cases). Every sentence adds value with no redundancy.

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

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

No output schema, but the description explicitly lists return fields (start/end dates, alert level, severity, affected port count, impacted population) and provides filter examples. Covers the essential information for an agent to understand the output.

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

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

Schema coverage is 100%, so the parameters are fully described in the schema. The description provides examples but does not add new semantic details 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 it returns port-affecting disruption events with specific attributes (start/end dates, alert level, severity, etc.). It distinguishes from siblings like recent_alerts and chokepoint_status by specifying the types of events tracked (tropical cyclones, floods, etc.).

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

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

Provides explicit use cases like 'what disrupted shipping in the last month' and 'which port closures hit our supply chain'. Does not explicitly state when not to use or list alternatives, but the context signals and sibling list offer differentiation.

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 context beyond annotations: scoped by agent identifier, persistent for authenticated users, 24-hour retention for anonymous. Annotations already indicate idempotent and non-destructive behavior, but description fills in storage semantics.

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

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

Five sentences, front-loaded with purpose statement, no filler. Every sentence adds value: purpose, usage, storage details, and pairing with other tools.

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?

Tool is simple with only two required string parameters and no output schema. Description covers storage duration, scoping, and relationship to sibling tools, making it fully complete for an AI agent to use correctly.

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

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

Schema covers both parameters with clear descriptions (key as string with naming convention, value as any text). Description reiterates the pairing concept but does not add new information per parameter. Baseline 3 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 uses a specific verb ('save') and resource ('data for later reuse'), clearly distinguishing it from sibling tools like recall and forget. It states exactly what the tool does: store key-value pairs for reuse across sessions.

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 describes when to use ('discover something worth carrying forward') and what to store ('resolved ticker, target address, user preference'). Mentions alternative tools (recall, forget) and retention policies for different user types.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it discloses source labeling, explicitly reports unresolved identifiers, handles graceful degradation of LEI/FIGI enrichment, and reveals that each call cascades through multiple endpoints. This exceeds what annotations provide and prepares the agent for partial-failure scenarios.

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

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

The description is front-loaded with query examples and a clear directive. It is somewhat long and dense, especially the company section nested in parentheses, but each detail (unresolved handling, degradation, source labeling) serves a purpose. The structure could be improved with bullet points, but it is not overly wasteful.

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

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

With no output schema, the description fully carries the responsibility of explaining return values. It thoroughly describes what is returned for both entity types, including ownership data, unresolved identifiers, and drug citation format. It also covers failure modes and graceful degradation, making the tool's behavior predictable and usable by an agent.

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

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

Schema description coverage is 100% and the schema already explains each parameter with examples ('AAPL', '0000320193', 'ozempic'). The description restates the same examples and adds no new parameter-level meaning. The baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the verb and resource: resolve a natural-language name to official identifiers. It lists typical user queries and specifies the supported entity types (company, drug) and what identifiers are produced (CIK, LEI, FIGI, RxCUI). This distinguishes it from sibling tools like entity_profile or compare_entities, which provide downstream analysis.

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

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

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces multiple manual lookups. However, it does not explicitly name alternative tools for when you already have an ID or need a different kind of lookup, so it falls short of the highest benchmark.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds transparency about the internal process (probes each entity with ai_visibility_check) and output format (ranked list with score, confidence, signal density). 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 concise at three sentences, each serving a purpose: main action, operational details, and use case. No redundant information; front-loaded with the core 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, the description adequately covers output structure (ranked list with score, confidence, signal density). It explains how the tool works (calling ai_visibility_check) and provides a realistic example. All necessary context for an agent to understand when and how to use it is present.

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

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

Schema coverage is 100%, but the description adds valuable context: the first entity is the 'subject', array size constraint (2-8), example for context, and usage guidance for models ('Omit for just workers-ai'). These details enhance understanding beyond the schema.

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

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

The description clearly states a specific verb ('Compare', 'Probes', 'ranks', 'surfaces') and resource ('AI visibility across multiple entities'). It explicitly describes the tool as a side-by-side comparison, distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 use case ('competitive AI-marketing audits') and implies that for a single entity one should use ai_visibility_check instead. It mentions treating the first entity as the subject. While not explicitly stating when not to use, the purpose is well-defined.

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 details the tool's behavior beyond annotations: it fans out to two external services, returns a specific summary block with fields like is_latest, advisory_count, bundle_kb_gz, etc., and warns about bundlephobia's first measurement time (5-30s) with graceful degradation via 'sources_failed'. Annotations already indicate read-only, idempotent, and non-destructive, which the description does not contradict.

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

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

The description is front-loaded with a clear one-sentence summary, followed by details on usage, output fields, and warnings. Every sentence adds value without redundancy. It is well-structured and appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description comprehensively explains the return value structure (summary block, per-advisory detail, links, alternative versions). It covers inputs, behavior, ecosystem scope, error handling, and partial failures, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with both parameters documented. The description does not add significant meaning beyond the schema: it mentions that version defaults to latest, which is already in the schema. Baseline 3 is appropriate as the schema carries the burden.

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

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

The description clearly states the tool's composite purpose: a single call to check if an npm package should be added to a project, fanning out across deps.dev and bundlephobia. It specifies the checks (license, advisories, bundle size, etc.) and distinguishes itself from other tools by targeting npm packages specifically.

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: 'when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also sets boundaries by noting that other ecosystems (PyPI, Maven, etc.) should use a different tool (deps.dev:version directly). This provides clear context and excludes 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 provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character limit (200K chars with truncation and flagging), and that passages include offsets for verification. This goes beyond what annotations provide.

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

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

The description is front-loaded with the core purpose, and each sentence adds value (usage guidance, pairing with another tool, technical details). It is slightly dense but appropriate for the informational content.

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

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

Given no output schema, the description sufficiently explains the return format (passages with offsets and scores), the algorithm (chunking, embeddings, similarity), the truncation behavior, and the intended workflow with a sibling tool. It is complete for an informed selection by the AI agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the schema with examples (e.g., query examples) and clarifies the character limit, but does not add new syntactic or semantic details beyond what the schema already provides for each parameter.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' and returns passages with character offsets and similarity scores. It distinguishes itself from sibling tools by explicitly pairing with 'ask_pipeworx_grounded' and contrasting with general fetch operations.

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

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

The description explicitly advises using the tool 'when the record is too big to cram into the prompt' and explains how it saves context. It also hints at when not to use alternatives by describing the pairing with another tool, though it could be more explicit about exclusions.

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

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

The annotations include idempotentHint: true, but the description says 'Create a new subscription', implying non-idempotent creation. This contradiction is significant and reduces transparency. Additionally, no details are provided about what happens if a duplicate subscription is created.

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

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

The description is well-structured and front-loaded, but slightly lengthy due to extensive examples. Every sentence adds necessary context, making it appropriate for the tool's complexity.

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

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

Given the tool's complexity with nested objects and dynamic parameters, the description is complete. It covers authentication, all subscription types, delivery channels, rate limits, and informs about the returned subscription ID (since 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?

The input schema has 100% description coverage, but the description adds substantial value with detailed examples, required fields, and constraints for each parameter type. For instance, it clarifies the structure of 'params' and 'delivery' objects beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It lists supported types and their parameters, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly specifies when to use this tool (creating subscriptions), prerequisites (Pipeworx OAuth account), and provides examples for each type. It implicitly guides away from anonymous/BYO accounts and describes delivery channels and limits.

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 it's read-only, open-world, and idempotent. The description adds value by detailing return structure (category-bucketed questions) and that it draws from a live catalog, without contradicting annotations.

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

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

Description is well-structured with example queries first, then explanation of return and usage. It is appropriately detailed but could be slightly more concise.

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

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

For a simple tool with one optional parameter, no output schema, and rich annotations, the description is complete: it explains return format, usage as onboarding, and optional focus.

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

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

Schema has 100% coverage with one parameter. The description adds meaning by listing example topic values (e.g., finance, pharma) and explaining the effect of omitting the parameter.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions with exact tool+argument shapes, distinguishing it from sibling tools 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?

Provides clear guidance to use this tool first when unsure of Pipeworx's capabilities, and explains optional topic filtering. However, it 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?

Adds significant behavioral context beyond annotations: ownership enforcement and deactivation semantics (not deleted, historical events remain). Complements the annotations effectively.

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

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

Two sentences, no wasted words. Front-loaded with the main action, making it easy for an agent to parse quickly.

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 clear annotations, the description fully covers the purpose, constraints, and behavioral nuances. No gaps identified.

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

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

Schema coverage is 100% and the description does not add extra meaning beyond the schema's parameter description. Baseline of 3 is appropriate.

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

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

Description clearly states the action ('Cancel a subscription by id'), specifying the verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when to use. Does not explicitly mention alternatives, but the constraint is well understood.

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

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

Despite strong read-only/idempotent annotations, the description adds substantial behavioral context: it explains the two-pipeline routing, the meaning of each verdict, and critically warns that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also discloses that 'unsupported' means no source was found, adding nuance beyond the annotations.

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

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

The description is dense but well-organized: trigger phrases, usage, pipeline details, return values, and caveats are logically grouped. No sentence is purely filler, though the length is above average. It could be slightly tighter by separating the efficiency note, but the structure earns it a 4.

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

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

For a tool with two parameters and no output schema, the description is remarkably complete. It covers expected inputs, return verdicts, citation format, error semantics, and edge cases (could_not_verify vs unsupported). It also explains the value proposition over sequential calls, making it sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% for both parameters, so the schema already documents them. The description adds value by explaining that tolerance_pct overrides the tolerance implied by the claim wording, defaults to implied/capped at 5, and is useful for hallucination detection. It also gives concrete examples for the claim parameter, making both parameters clearer than the schema alone.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources' using the verb 'validate' / 'verify' with the resource 'claim'. It also distinguishes itself from siblings by describing a fast path for company-financial claims and a grounded fallback for all other facts, and notes it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides natural-language trigger phrases. It also explains the routing logic for financial vs. non-financial claims, giving clear usage context. It stops short of naming alternative tools or stating when not to use it, so it doesn't fully reach a 5.

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