Osrm

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: free default model, BYO key for Anthropic with direct cost, return per-model data including 'raw_response' and 'signals'.

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 ~70 words, front-loaded with action and purpose, then details parameters and use cases. Every sentence adds value with zero 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 no output schema, the description explicitly lists return fields: per-model {score, confidence, signals, raw_response} + combined view. It also covers all 4 parameters, their defaults, and use cases. For a tool with 4 params and no nested objects, this is fully complete.

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

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

Schema description coverage is 100%. The description adds context beyond schema: default model is Workers AI Llama-3.3-70b (free), and explains _apiKey is needed for Anthropic. This helps an agent understand the parameter roles better.

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 probes LLMs for visibility and scores it (0-100). It specifies verb 'probe' and 'score', resource 'LLMs' and 'visibility'. It distinguishes from siblings like 'entity_profile' or 'scan_competitor_ai_presence' by focusing on AI model knowledge scoring.

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

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

The description gives explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It lacks explicit alternatives or when-not-to-use, but context is clear. No mention of when to use other 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it routes to one of 5,439 tools, fills arguments, returns structured answers with citations, works on every tier, and makes one fast call. It doesn't overpromise or contradict 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 longer than average but front-loads the core directive ('PREFER OVER WEB SEARCH') and organizes content into 'Use whenever', 'Examples', and 'Step up only when needed'. Every sentence contributes to guidance; no wasted words, though it could be tightened slightly.

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 broad routing tool with no output schema, this description fully covers what the tool does, when to use it, what it returns (structured answer with citation URIs), and how it relates to siblings. It also notes account/tier behavior and performance characteristics.

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 6 parameters, with each alias explicitly described as an alias for 'question'. The description adds example queries and general usage patterns, but no new parameter-level semantics beyond what the schema already clearly delineates. Per rubric, high schema coverage yields a baseline of 3.

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

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

The description clearly states the tool's function: routing questions to a wide range of authoritative data sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives (ask_pipeworx_grounded, 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?

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists question types and example phrasings, and states when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). Also notes breaking-news handling.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description adds key behavioral context: it currently matches ask_pipeworx exactly because no candidate is active, and when a candidate is under test, routing improvements are enabled live. It also clarifies that it is a full working router, not a fallback stub.

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

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

The description is a single, efficiently structured paragraph of four sentences. It front-loads the beta identity, explains the identical nature, states current status, and gives usage intent—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 variant of an existing tool, the description is quite complete. It explains the relationship to the stable version, the experimental state, current behavior, and response shape. It does not enumerate the 5,439 tools or routing details, but that is presumably covered by ask_pipeworx's documentation and not necessary here.

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 6 parameters with descriptions (100% coverage), including aliases for 'question'. The description only says 'same arguments' without adding further meaning beyond the schema, so it does not elevate above the baseline for high schema coverage.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with 5,439 tools, same arguments, and same response shape. It explicitly positions it as the experimental edge versus the stable ask_pipeworx, distinguishing it from its primary sibling.

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 to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared with the stable router. It implies the stable ask_pipeworx should be used for non-experimental routing, but does not explicitly exclude other alternatives like ask_pipeworx_grounded.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It discloses the refusal mechanism with specific refusal_reason values ('not_in_source', 'no_tool_match', etc.), explains that answers are grounded only in tool results, and reveals the cost of an extra LLM call. It adds significant behavioral context not captured by annotations.

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

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

The description is dense but well-structured. It front-loads the core purpose in the first sentence, then explains mechanism, return structure, refusal reasons, use cases, and cost trade-off. While it is longer than some, every sentence carries information and the use of hyphens/separators improves readability.

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

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

Since there is no output schema, the description compensates fully by detailing the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal scenarios. It also covers the routing behavior and cost trade-off, making the tool's behavior and expectations complete for an agent.

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

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

Schema coverage is 100% and the description adds no new parameter-level semantics. The schema already explains that all six parameters are aliases for a natural-language question. With high coverage, the baseline of 3 applies; the description does not need to repeat what the schema states.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling ask_pipeworx by explaining it 'EXTRACTS the answer using ONLY what the tool result contains' and returns evidence. This is a specific, non-tautological statement of purpose.

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

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

Usage guidance is explicit: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, providing a clear trade-off between this tool and the alternative. This is strong when-to-use / 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: resolver contract (market_match_confidence, alternatives), parent_event extractor, news fallback fields, safety blocking for low-confidence/closed/wide-spread matches, and resolution-rule risk parsing. All consistent 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 well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and use cases. While some details could be condensed, the structure 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 (multiple fan-out types, response structures, safety checks, error states), the description covers all relevant aspects without requiring an output schema. It explains behavior for edge cases like closed markets, wide spreads, and resolution risks.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the parameter types (slug, URL, text) and briefly mentions depth and include_raw defaults/effects, but adds little semantic nuance beyond the existing 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 opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which is a specific verb+resource+method. It distinguishes from sibling tools like ask_pipeworx and deep_research by explicitly targeting Polymarket betting decisions.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete examples of classifier-specific fan-outs. However, it does not explicitly mention when not to use this tool or list 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 indicate safety (readOnly, idempotent, openWorld). Description adds valuable behavioral details: parallel call, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

Description is detailed but each sentence adds value. Structured with query examples, usage directive, parameter clarifications, and result format. Could be slightly more concise, but no wasted words.

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

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

Given 2 required parameters and no output schema, the description fully covers purpose, input format, data details, sorting, and alternative guidance. Agent can confidently invoke tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: explains type values with data pulled (financial vs adverse events), clarifies values array format (tickers/CIKs vs drug names), and specifies min/max items. Provides 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 it provides side-by-side comparison of 2-5 companies or drugs, with specific query examples. It distinguishes from sibling tools (e.g., entity_profile) by explicitly recommending this over sequential single-entity lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Does not explicitly state when not to use, but context implies it is for comparisons only, which is adequate.

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

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

Adds extensive behavioral context beyond annotations: parallel decomposition, return format (evidence+confidence+source+citation), gaps[] never invented, second-hop depth behaviors, contradictions[] for deeper modes, excerpting semantics, and expected latency. No contradiction with readOnly/openWorld/idempotent hints.

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

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

Long but appropriately sized for the tool's complexity; every sentence adds value (account requirement, alternatives, return packet, gaps, depth modes, timing). Front-loaded with the most critical operational constraint (account) and quick redirect to ask_pipeworx, then proceeds to core function and behavior.

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

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

Despite no output schema, description thoroughly specifies return contents, error behavior (gaps[]), contradictions[], citation format, and performance expectations. Covers prerequisites, alternatives, and limitations (breaking news gaps), making the tool's behavior fully comprehensible in context.

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

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

While schema covers 100% of parameters, description enriches them: explains depth levels ('quick=3 ... standard=5 ... thorough=8 paid') and clarifies that question can be 'Broad/multi-part is fine'. Adds practical meaning to both parameters beyond their schema descriptions.

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

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

States a specific verb ('research') and resource ('Pipeworx's 1412 STRUCTURED data sources') while distinguishing itself from siblings: 'this is NOT open-web search' and explicitly contrasts with ask_pipeworx. The description clearly identifies the tool's core function of decomposing questions and routing to parallel tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking news 'prefer ask_pipeworx'. Also covers prerequisites ('ACCOUNT REQUIRED') and alternatives if not signed in, making usage boundaries unmistakable.

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=true and idempotentHint=true, but the description adds valuable information: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations by explaining output format and reusability.

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

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

The description is a single paragraph that front-loads the purpose. It is somewhat dense with examples and domain listings, but every sentence adds value. It could be slightly more concise, but it remains informative and structured clearly for an agent.

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

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

Given the tool has no output schema, the description compensates by explaining that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It covers the limit parameter implicitly and explains the return format. For a discovery tool with 6 parameters and full schema coverage, this is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions that the query parameter accepts natural language and gives examples like 'analyze housing market trends,' but these are already present in the schema's examples. The description does not add significant new meaning or usage nuances for the parameters, so it stays at baseline.

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

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

The description clearly states the verb ('Find tools') and resource ('tools by describing the data or task'), and lists specific domains (SEC filings, FDA drugs, etc.). It differentiates itself from sibling tools by advising 'Call this FIRST when you have many tools available and want to see the option set.' This is a specific, valuable use case that sets it apart from other tools.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a comprehensive list of topics. It also tells the agent to 'Call this FIRST' when exploring options. While it doesn't name specific sibling tools as alternatives, it provides clear contextual guidance for when to use this tool over others.

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 true, and destructiveHint false. The description adds valuable context: it fans out across multiple sources, soft-fails for patents (Sunset May 2025), and returns specific fields. 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 front-loaded with concrete query examples, then explains the multi-source behavior and return fields. It is relatively long but each sentence adds value. Could be slightly more concise by grouping similar info, but overall well-structured.

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

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

No output schema is provided, so the description must explain return values. It does so comprehensively: lists fields like cik, company_name, recent_filings (including URIs), fundamentals, patents (with caveat), news, LEI. This fully prepares the agent for the tool's 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 description coverage is 100%, with each parameter fully documented (type enum, value with format examples). The description essentially repeats the schema's guidance on value format. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description explicitly states the tool provides a full cross-source profile of a US public company in one parallel call, with example queries. It clearly differentiates from sibling tools like resolve_entity and compare_entities by specifying when to use this (holistic view) vs chaining other lookups.

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

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

The description gives explicit when-to-use guidance ('ALWAYS PREFER over chaining...'), when-not-to-use ('names not supported — use resolve_entity first if you only have a name'), and notes preferred scenarios. This leaves no ambiguity for the agent.

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. Description adds behavioral context (e.g., 'clear sensitive data') and confirms deletion of memory, supplementing annotations without contradiction.

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

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

Two efficient sentences: first defines purpose, second gives usage context. 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?

Covers purpose, usage, and context adequately for a simple tool with one parameter and full annotations. No output schema needed, so completeness is high.

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

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

Schema coverage is 100% and the parameter description is clear. The tool description adds no further nuance about the key, meeting baseline but not exceeding.

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 ('Delete') and resource ('previously stored memory by key'), and distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Provides explicit when-to-use conditions: 'context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with related 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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool fetches the page, extracts key elements, and emits standard markdown. This aligns with annotations and provides useful context about the operation being non-destructive and idempotent.

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

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

The description is a single paragraph with no filler. The key action is front-loaded, and every sentence adds value: what it produces, how it works, and usage scenarios.

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 only 2 parameters, no output schema, and safety annotations, the description is fully adequate. It explains the output format, usage context, and behavior without gaps.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add new semantic meaning beyond the schema; it just restates the purpose of the link limit implicitly.

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 uses specific verb 'Generate' and resource 'llms.txt file', and states the action: generates a production-ready llms.txt for any URL. It distinguishes itself from sibling tools by focusing on a specific output format and use case for AI crawlers.

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 three use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not specify when not to use or provide alternatives, 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the returned fields, confirming the scope (caller's subscriptions), and noting the optional parameter include_inactive. 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 two sentences with no wasted words. The first sentence states purpose and returns, the second gives usage guidance. Well-structured and efficient.

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

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

For a simple tool with one optional parameter, no output schema, and comprehensive annotations, the description covers all needed context: what it lists, returned fields, and when to use it. No gaps.

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

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

Schema coverage is 100% (1 parameter fully described). The description does not add additional meaning beyond the schema's description of include_inactive. 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 the verb 'list', resource 'subscriptions', and scope 'caller's active'. It lists returned fields, clearly defining what the tool does. This differentiates it from sibling tools like subscribe/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 advises using this tool 'before adding more subscriptions' or 'to find an id to cancel', giving clear usage scenarios. However, it does not explicitly mention when NOT to use it or suggest alternatives beyond the implied context.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable context such as using OSRM, handling noisy traces, and returning geometry and confidence, which enhances transparency beyond annotations.

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

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

The description is a single, information-dense sentence with key aspects presented upfront. Every part is relevant, and there is no wasted text.

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

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

Given the tool's complexity and the presence of an output schema, the description covers input format, optional parameters, and output characteristics. It is mostly complete, though a brief mention of the profile parameter would improve it.

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

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

Schema description coverage is only 33% (one of three parameters described in schema). The description partially compensates by explaining coordinates format and radiuses, but omits the 'profile' parameter, leaving ambiguity. Thus, it adds some but not 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?

The description clearly states it map-matches a noisy GPS trace to a road network using OSRM with specific input format and optional parameters. However, it does not explicitly distinguish this tool from its sibling 'route', which may also involve routing, so it loses a 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?

The description implies the usage scenario (noisy GPS trace matching) but does not provide explicit guidance on when not to use this tool or suggest alternatives. Sibling tools like 'route' exist but are not mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. Description adds the specific snapping behavior, which is consistent and provides 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?

Single sentence, no redundancy, directly conveys the core function. No waste.

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?

Adequate for a simple snapping operation. Does not explain return behavior, but output schema may cover that. Parameter semantics are missing, but overall acceptable for a low-complexity 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 low (25%), yet the description does not elaborate on any parameters (e.g., 'number' for alternatives, 'profile' for mode). It adds no semantic 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?

Description clearly states the action ('snap'), the resource ('a single point'), and the target ('nearest road segment'). It is specific and distinguishes from sibling tools like 'route' or 'trip'.

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?

No guidance on when to use this tool versus alternatives (e.g., 'route', 'match'). The description does not mention use cases 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?

All annotations are false, so the description carries the burden. It discloses rate limiting (5/day), that it's free and doesn't count against quota, that feedback directly affects roadmap, and instructs not to paste end-user prompts – useful behavioral and data-handling context. 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 eight sentences long, which is verbose for an MCP tool, but every sentence carries operational value. Some details (team reads digests daily, free, doesn't count quota) are secondary but not wasted. Slight deduction for length compared to more concise alternatives.

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 simple feedback nature, the schema covers all parameters, and the description covers purpose, usage, boundaries, rate limits, and message framing, the description is complete enough for an agent to use it effectively. No output schema is needed for a fire-and-forget feedback tool.

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

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

The input schema is fully described (100% coverage), so the baseline is 3. The description adds extra value by explaining when to choose each enum type and how to phrase the message in terms of Pipeworx tools/packs, which is not in the schema. This pushes it above baseline to 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 opens with a clear verb and object: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the four feedback types (bug, feature/data_gap, praise) and is clearly distinct from sibling tools like ask_pipeworx or discover_tools.

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

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

The description gives explicit when-to-use guidance for each type (bug, feature/data_gap, praise) and an explicit exclusion for tools from other MCP servers, redirecting the user elsewhere. It also clarifies how to identify Pipeworx tools, making the decision boundary unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: data source (CF analytics-engine), no PII, caching (5min-1h), and that it's a self-aggregating signal. 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 extremely concise: 3 sentences covering purpose, output, parameter guidance, and use cases. Information is front-loaded (first sentence states core function). Every sentence adds value with no fluff.

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

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

Given a simple tool with 1 optional parameter, no output schema, and rich annotations, the description fully covers purpose, usage context, parameter behavior, caching, and data provenance. An agent has all information needed to decide invocation.

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

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

The only parameter 'window' is fully described in the schema with enum and description. The description adds extra meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enhances decision-making 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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('returns', 'discovering', 'confirming') and distinguishes from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on aggregate trending 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 three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use case) and explains how window size affects results. While it doesn't explicitly list when not to use or name sibling alternatives, the context is clear and actionable.

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

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

Discloses detailed behavioral traits beyond annotations (readOnlyHint, idempotentHint): includes semantic anchor, partition filter, fill check logic, and conditions for not trading (realizable_edge_pp <= 0). No contradiction with annotations; adds rich context for decision-making.

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

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

Well-structured: first sentence states core purpose, then explains modes, technical details, response format, and fill check. Every sentence adds value without redundancy. Despite length, it is front-loaded and efficiently conveys necessary 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?

Comprehensive for a tool with 2 optional parameters and no output schema. Describes return fields (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, etc.), covers edge cases (placeholders, similarity check), and explains fill check. Completely equips agent to understand tool behavior and results.

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

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

Schema coverage is 100% but description adds significant meaning: explains what each parameter does (e.g., event slug examples, topic seed questions), provides mode-specific behavior, and details underlying checks (partition_check, cross-event scanning). Elevates parameter understanding well 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no arguments (trending_scan), event mode, and topic mode, each with specific behavior. This differentiates 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. Recommends event mode for specific markets and mentions using polymarket_fill_risk for custom sizing. Clear context and alternatives provided.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant behavioral context: caching at KV level keyed on all knobs (1 hour), details on how each segment computes its edge (e.g., lognormal barrier, GDELT volume ratio, partition_overround with bias correction, concentrated_longshot gates), and diagnostics to explain empty segments. No contradictions with annotations.

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

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

The description is dense and technically detailed, but well-structured with clear sections (model families, tradeable-edge knobs, response structure). Every sentence provides specific information, though length is justified by complexity. It is front-loaded with the core purpose and then provides necessary depth. Could be more concise 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 the tool's complexity (9 parameters, 3 output segments, no output schema), the description thoroughly explains return value fields (edge_pp_net, kelly_fraction, kelly_fraction_half, market.liquidity, market.spread_pp, market.volume, 24h-move warning) and diagnostics (concentrated_longshot funnel counters, category_counts, filter_skips). The explanation of why Fed bets are excluded adds context. The description leaves no significant gaps for an agent to understand the tool's behavior.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by explaining the 'TRADEABLE-EDGE KNOBS' (min_liquidity, max_spread_pp, min_partition_leg_kelly) and their effect (e.g., 'knobs drop opportunities where edge isn't realizable'). It also clarifies how min_kelly and min_partition_leg_kelly interact differently for single-leg vs. partition opportunities. This additional context raises the score above baseline.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarkets and return opportunities where Pipeworx data disagrees with market price.' It specifies the use case ('what should I bet on today') and breaks down the three response segments, distinguishing this tool from siblings by its focus on Pipeworx disagreement and edge scanning.

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

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

The description explicitly states when to use the tool ('agents discover opportunities without paging hundreds of markets'), explains the three model families and their conditions, describes tradeable-edge knobs for filtering, and notes that Fed bets are surfaced but excluded from ranking. This provides clear guidance on tool usage 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?

The description extensively explains behavior beyond annotations: details return structure (tracked, expired, snapshot_dates), signed edge_pp_net, snapshot write conditions, gaps meaning, and TTL limits. 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 well-structured and every sentence adds value; it could be slightly more concise, but the information density is high.

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 and lack of output schema, the description provides a complete picture of return fields and behavioral nuances (decay computation, snapshot gaps, TTL), enabling correct agent usage.

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

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

Schema coverage is 100%, but description adds value by explaining default values and the meaning of 'window' as snapshot family, and clarifying the 'days' range (default 14, max 30) beyond schema's clamp.

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 answers 'how long has this edge existed and is it shrinking?' and distinguishes from sibling tools by focusing on persistence and decay telemetry from snapshots, not just current edges.

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

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

Provides clear context for when to use (to evaluate edge freshness vs. decay) and hints at why fresh vs. old edges matter, but does not explicitly mention when not to use or list 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?

Adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint false): walks the ladder, returns specific fields, explains basket mode risks (thin_legs, forced_directional_risk), and verifies partial fills convert arb into directional risk. No contradiction with annotations.

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

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

The description is well-structured with headings (SINGLE-MARKET, BASKET), bullet points for return fields, and clear risk notes. It is somewhat lengthy but every sentence adds value given the complexity. Slightly verbose but appropriate.

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

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

Fully covers input, dual modes, return fields, and risks. No output schema exists, but the description enumerates all return fields (top_of_book, vwap_fill_price, etc.) and explains basket-specific outputs (capture_ratio, profit_usd, thin_legs, etc.). Complete for a complex tool.

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

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

Schema description coverage is 100%, and the description adds value by explaining defaults (size_usd default 1000, side default auto), basket-mode interpretation of size_usd, and side auto-detection. It clarifies behavior 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes single-market and basket modes, and specifies it should be used before acting on arbitrage signals or trades above $500. It differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains risks. It also states 'REQUIRES one of `market` or `event`', 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 read-only, idempotent, non-destructive. The description adds significant behavioral detail: it explains compatibility warnings for mismatched bet shapes and temporal misalignment, counters for dropped comparisons, and the fact that real arbitrage opportunities are rare. 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 well-structured with clear sections (modes, response, safety fields) and front-loaded with purpose. However, it is somewhat verbose in the safety field explanation; a few sentences could be tightened without losing meaning.

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

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

Given the tool's complexity (3 parameters, no output schema), the description thoroughly explains the response structure: each venue's prices, matched spreads, and safety fields. It covers all necessary context for an agent to understand when and how to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context: explains the topic parameter enumerates 10 macro shortcuts, and that explicit parameters override the topic. Provides concrete examples, enhancing understanding beyond the schema alone.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by specifying 'cross-venue' and mentions it compares bet shapes for equivalence, differentiating it from single-venue tools like polymarket_arbitrage.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers) and provides examples. Warns that most pre-mapped topics return compatibility warnings, setting appropriate expectations. Specifies conditions where spreads are not tradeable (temporal misalignment, non-equivalent bet shapes).

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

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

Description adds scoping detail (anonymous IP, BYO key hash, account ID) beyond annotations. 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?

Three efficient sentences with front-loaded main action. 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?

Covers usage, scoping, and sibling pairing. Lacks description of return format (string or list) but acceptable for 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 coverage 100%, baseline 3. Description explains that omitting key lists all saved keys, adding practical nuance beyond schema.

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

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

Description clearly states it retrieves a saved value or lists all keys. Distinguishes from siblings 'remember' and 'forget' by mentioning them explicitly.

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 when to use (look up context stored earlier) and how to list all keys (omit argument). Does not explicitly exclude cases but pairs with siblings for completeness.

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 states that mark_read:true flags events as read, which modifies the feed state. This contradicts the annotation readOnlyHint=true, which implies no state mutation. The description does disclose this behavior, but the contradiction to annotations is a serious inconsistency that undermines trust.

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

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

The description is a single paragraph of five sentences, front-loaded with the core purpose. It is concise and each sentence adds value (purpose, return fields, filtering options, mark_read effect, alternative endpoint). Minor room for improvement in structuring with bullet points.

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 five optional parameters and no output schema, the description covers essential return fields, filtering, mark_read state change, and provides an alternative access method. It is sufficiently complete for an agent to use the tool effectively, though it could briefly mention pagination or limit behavior.

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

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

Schema coverage is 100% with descriptions for all five parameters. The description adds usage context (e.g., 'e.g. "sec_8k"' for type) but does not introduce new meaning beyond the schema. Baseline 3 is appropriate as the description merely reinforces existing schema information.

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 begins with 'Pull fired events from your subscription feed,' clearly stating the verb (pull) and resource (fired events). It further enumerates return fields (source, citation_uri, raw payload). However, it does not explicitly differentiate from sibling tools like 'recent_changes' or 'validate_claim', so it lacks explicit 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 provides explicit guidance on filtering by type and since, and on using mark_read to control read state for subsequent calls. It also mentions that polling works and provides an alternative endpoint for scripts/dashboards. However, it does not state when not to use this tool or suggest alternative tools for different use cases.

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 valuable behavioral context: the tool fans out to multiple sources, has a fallback chain (GDELT → GNews), and soft-fails for USPTO. This goes 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 concise yet comprehensive. It front-loads the core purpose, then efficiently covers sources, parameters, and sibling differentiation without redundancy. 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 lacking an output schema, the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all essential aspects: purpose, parameters, sources, fallback, and when to use an alternative. Complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the `since` parameter's relative shorthand (e.g., '7d', '30d') and the `value` parameter's accepted formats (ticker or CIK). This extra context justifies a score of 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 clearly states it provides a change feed for a company in a time window, listing example queries and sources. It explicitly distinguishes from the sibling `entity_profile` tool, which is used for static profiles.

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

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

Explicitly states when to use this tool (for recent changes) and when to use `entity_profile` instead. Provides thorough guidance on the `since` parameter with examples, and explains fallback behavior among sources.

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 behavioral details beyond annotations: persistence differences between authenticated (permanent) and anonymous (24 hours), scoped by identifier. No contradiction with annotations. IdempotentHint is consistent.

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

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

Well-structured: purpose first, then usage guidance, then storage details, then pairing with other tools. 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 no output schema, description fully covers behavior for an agent: what is stored, scoping, persistence, and how to retrieve/delete. No gaps.

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

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

Schema coverage is 100%, but description adds value with naming conventions for keys and examples for values. Significantly enhances 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?

Clearly states 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from siblings recall and forget. Provides examples of use cases.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Provides concrete examples. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that each call cascades through multiple lookup endpoints and details what each type returns (e.g., ticker, CIK, citation URI for companies). 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 concise, well-structured, and front-loaded with purpose and examples. Every sentence adds value, and the use of line breaks improves readability.

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

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

With no output schema, the description fully explains return values for each entity type, including citation URIs. It also notes that the tool replaces multiple manual lookups, providing complete context for an agent.

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

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

Schema coverage is 100%, but the description adds meaningful context: accepted formats (ticker, CIK, name for company; brand/generic for drug), auto-disambiguation, and return field details. This goes beyond the schema's basic 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 clearly specifies the tool resolves names to canonical identifiers (ticker, CIK, RxCUI) for companies and drugs, with concrete examples. It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly states when to use the tool (when you have a name but need an ID) and lists supported types and their outputs. However, it does not explicitly state when not to use it or provide direct 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds only 'fastest route' which is purpose-oriented, not behavioral. No mention of side effects, performance, or limits 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?

Single sentence with front-loaded verb and resource. No redundancy, every word earns its place.

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

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

Given the presence of output schema and detailed parameter descriptions, the description captures the essential function. However, lacks context for sibling differentiation and usage guidelines, leaving gaps for effective tool selection.

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

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

Schema description coverage is 100%, so all parameters are well-documented in schema. Description adds no extra meaning beyond the schema's parameter descriptions, meeting the baseline for this dimension.

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 verb (Compute), resource (route), and key constraint (fastest) with waypoints. It effectively communicates the tool's purpose but does not explicitly distinguish from sibling 'trip' which might be similar.

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?

No guidance on when to use this tool vs alternatives like 'trip'. Missing information on prerequisites, suitable scenarios, or exclusions, leaving the agent to infer context.

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

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

The description adds significant behavioral context beyond annotations: it reveals the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This fully discloses the mechanism and output. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is three sentences: purpose, mechanism, use case. Front-loaded with key information. Every sentence serves a purpose with no filler.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density) and notes the underlying probe call. It covers the main behavioral aspects, though it could optionally mention any error conditions or rate limits. Overall sufficient 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?

With 100% schema coverage, the description still adds value by clarifying that the first entity in the array is treated as the 'subject' for narrative purposes and explaining model options with usage notes (e.g., 'workers-ai' as default, 'anthropic' requires key). It adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check per entity and ranking results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more 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 directly states it is 'useful for competitive AI-marketing audits' and gives an example. While it does not explicitly exclude alternatives or provide when-not-to-use guidance, the context of comparing multiple entities implies it is the right choice for side-by-side analysis.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds concrete behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed field lists timeouts. This goes beyond annotations.

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

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

Description is relatively long but well-organized: front-loaded with core purpose, then usage, then details. Every sentence adds value, though slightly verbose.

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

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

Given no output schema, description fully explains return block fields, partial failure behavior, and provides sufficient context for a complex composite tool.

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

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

Schema has 100% coverage, so baseline is 3. Description confirms package is npm name and version optional, mentions scoped packages and default to latest. Minimal additional meaning 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 is a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It uses specific verbs and distinct resources, differentiating it from sibling tools.

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

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

Explicitly says when to use: 'when an agent asks is X safe/popular/small or what does adding lodash cost me'. Also states ecosystem limitation (npm only, v1) and points to alternatives for other ecosystems.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich detail: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation and flag), and offset guarantees for verification. 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 (4-5 sentences) and well-structured. It front-loads the purpose, provides usage context, and details behavior without unnecessary words. 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 the tool has 3 parameters and no output schema, the description comprehensively covers input requirements, output format (passages with offsets and scores), behavioral details (embedding model, windowing, truncation), and pairing with other tools. It leaves no critical gaps for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful examples (e.g., 'supply-chain risk') and clarifies the types of text (SEC 10-K, article, tool result) and queries, enhancing understanding 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 performs semantic search inside a fetched record, specifying the verb 'search' and the resource 'inside a fetched record'. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing and contrast with whole-document grounding.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt' and provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Beyond annotations, description details OAuth requirement, delivery channel constraints (SMS verification/cap, webhook HMAC/auto-disable), and persistence limitations for anonymous/BYO accounts. 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?

Well-structured and front-loaded with purpose and return value. Some detail could be moved to schema descriptions, but the text is efficient and earns its length.

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

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

Covers all necessary aspects: authentication, types, parameters, delivery channels, and return value (including one-time webhook secret). Complete for a subscription creation tool without 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?

Despite 100% schema coverage, the description adds substantial value with type-specific examples and detailed constraints for delivery options, making parameter usage much clearer.

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 creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides explicit context for when to use (creating subscriptions) and important prerequisites (Pipeworx OAuth account). Does not explicitly state exclusionary cases, but the sibling context implies 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?

Beyond annotations (readOnly, idempotent, etc.), the description adds behavioral context: it returns example questions with tool+argument shapes, and can be called with or without a topic. 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?

Front-loaded with user query examples, then explains output and usage. Slightly verbose with all categories listed, but compact for the value conveyed. Clear 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?

Despite no output schema, the description explains exactly what is returned (bucketed example questions with tool+argument shapes). Covers all necessary context for an onboarding tool: purpose, alternative meta-tools, optional parameter.

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% (1 optional parameter). Description adds meaning by listing example topic values ('finance', 'pharma', etc.) and explaining the default behavior when omitted.

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 and resources: 'Returns category-bucketed example questions' with detailed categories (company financials, drugs, etc.). It clearly distinguishes from siblings by positioning itself as the 'onboarding entry point' for a new agent.

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 this FIRST when you do not yet know what Pipeworx can do for you' and 'or to learn how to call the meta-tools'. Also provides alternatives like ask_pipeworx, entity_profile, etc.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context (e.g., rate limits, output format). With strong annotations, the description's minimal contribution is acceptable.

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

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

The description is a single, precise sentence that directly conveys the tool's core function with no extraneous words.

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

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

Given the complexity of a matrix computation tool (5 parameters) and the presence of an output schema, the description is adequate but could benefit from a brief note on output structure (e.g., 'returns a 2D array'). However, the schema covers parameter details, so the description is mostly complete.

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

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

Schema coverage is 100%; all parameters are described in the input schema. The description does not add new parameter information, meeting the baseline expectation.

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 'Distance / duration matrix between source and destination points' clearly identifies the tool as computing a matrix of distances or durations, which is distinct from sibling tools like 'route' (single route) or 'trip' (trip planning).

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

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

The description implies bulk distance/duration computation but offers no explicit guidance on when to use this tool versus alternatives like 'route' or 'trip'. The presence of sibling tools provides context, but the description itself lacks usage 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minimal behavioral context beyond 'solve', which aligns with the annotations. It does not disclose constraints like optimization strategy, result format, or input limitations.

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

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

The description is a single concise sentence that efficiently conveys the core purpose. It avoids fluff, but the use of 'TSP-like' might require prior knowledge. Overall, it is well-structured for a simple tool.

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

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

Given the presence of an output schema and informative annotations, the description provides minimal but adequate context. It lacks details on typical use cases, coordinate format (though examples exist), and how 'TSP-like' differs from exact TSP. For a tool with five parameters, it is somewhat underdescribed.

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 60%, covering source, roundtrip, and destination with basic descriptions. However, the required 'coordinates' parameter and 'profile' lack descriptions. The tool description does not add clarity for these parameters, missing an opportunity to explain format or acceptable values.

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

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

The description clearly states the tool 'solves a TSP-like trip between multiple waypoints', using a specific verb and resource. It implies optimization for multiple waypoints, distinguishing it from a simple routing tool like 'route'. However, it could be more explicit about the difference.

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?

No guidance on when to use this tool versus alternatives like 'route' or other siblings. The description does not mention prerequisites, scenarios, or exclusions, leaving the agent to infer usage from the name and brief purpose alone.

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

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

Beyond annotations (destructiveHint=false), description explains behavioral nuance: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Adds valuable context about side effects.

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

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

Two sentences, no wasted words. Front-loaded with core purpose, then adds ownership and behavioral details efficiently.

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

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

For a simple one-parameter tool with no output schema, description fully covers purpose, constraints, and side effects. No gaps for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no further parameter details beyond schema (e.g., format or constraints), but this is adequate.

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' with specific verb and resource. It distinguishes from siblings 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?

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' Provides clear context on when to use but does not mention alternatives or when not to use.

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

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

Annotations already indicate readOnly and idempotent behaviors. The description adds useful context on the dual pipeline, return verdict types, and the tolerance mechanism, without contradicting annotations.

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

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

The description is front-loaded with query patterns but is somewhat lengthy; however, every sentence adds value, so it remains well-structured and not overly verbose.

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 covers essential aspects: usage, routing logic, return values (verdict types, evidence, reasoning), making it fairly complete for its complexity.

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

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

Schema coverage is 100% so baseline is 3. The description adds extra semantics by explaining the tolerance_pct parameter overrides the implied tolerance and providing claim examples.

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

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

The description clearly states it validates factual claims with specific query patterns and distinguishes from sibling tools by noting it replaces multiple calls and has a dedicated pipeline for company financials vs. other claims.

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

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

The description provides clear context for when to use ('check whether something a user said is factually correct') but does not explicitly state when not to use or name alternative sibling tools.

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