Openrouteservice

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral details: scoring mechanism, per-model response structure, combined view, and API key handling. No contradictions.

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

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

Three sentences, no wasted words. Front-loaded with core function and scoring. Efficient and scannable.

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 main purpose, parameters, return format, and usage scenarios. No output schema, but description compensates. Missing info (rate limits, model list) not critical for this simple tool.

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

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

Schema coverage is 100% (all parameters documented). Description adds value by explaining default model, free usage, how _apiKey works, and return format (per-model fields + combined view).

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 ('probe') and resource ('LLMs for visibility'), with specific scoring output (0-100 per model). Differentiates from sibling tools (e.g., deep_research, ask_pipeworx) by focusing on AI visibility audits.

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

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

Explicit use cases listed (AI-marketing audits, pre-launch brand checks, competitive monitoring). Clarifies default model and optional Anthropic probe with API key. No direct exclusions, but context is clear enough.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds useful context: it routes to 5,529 tools, fills arguments, returns citations, and works on every tier. This goes beyond the annotations without contradicting them, though it doesn't discuss rate limits or response details beyond citations.

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-loaded with the critical 'PREFER OVER WEB SEARCH' directive. Each subsequent sentence adds value: use cases, examples, and escalation paths. It is dense but not wasteful, 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?

For a complex tool with no output schema, the description fully addresses what it does, when to use it, alternatives, and expected output (structured answer with citation URIs). It covers edge cases like news queries and provides concrete examples, making it nearly complete for agent decision-making.

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

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

Though the schema covers the 'question' parameter with descriptions and aliases, the description enriches semantics by providing diverse examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and explaining it accepts natural language. This adds meaning beyond the schema's basic parameter 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 states the tool answers factual questions by routing to thousands of sources and returning structured data with citations. It distinguishes itself from sibling tools by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases like 'what is' and 'look up', and says 'START HERE for most questions'. It also gives precise when-not-to-use instructions by naming alternatives for grounded answers and deep research, exceeding the typical baseline.

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, non-destructive behavior. The description adds valuable context by explaining that routing improvements are enabled live under test, that currently no candidate is active, and that results are compared to the stable router to decide merges. It also confirms it is a full working router, not a stub, which 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 a compact paragraph of four sentences, each providing useful information: the beta status, identity with the stable router, current test state, usage guidance, and fallback behavior. It is slightly dense but commands no wasted words, making it appropriately sized for a complex experimental 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?

The description fully contextualizes the tool's relationship to ask_pipeworx, specifying that the response shape and arguments are identical, and covers the current experimental state and expected use. With no output schema, it deftly points to ask_pipeworx for return-value details, which is sufficient given the identical 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?

The input schema has 100% description coverage, with six parameters (q, text, input, query, prompt, question) all clearly aliases for the natural language question. The tool description adds no additional parameter-level semantics, so the schema carries the full burden. Baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with 5,529 tools, identical arguments and response shape. It explicitly distinguishes itself from the stable router by emphasizing candidate routing improvements and the experimental edge, which differentiates it from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that when no candidate is active it exactly matches ask_pipeworx, helping the agent decide. However, it does not compare against alternative tools like ask_pipeworx_grounded, leaving some ambiguity for non-routing-related choices.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behaviors: extraction restricted to tool result, explicit refusal reasons (not_in_source, no_tool_match, etc.), verbatim evidence, and additional LLM cost. No contradiction with annotations.

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

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

The description is dense and information-rich, with each sentence contributing useful details (return format, refusal reasons, use cases, cost). It is slightly longer than strictly necessary, but the front-loaded purpose and structured flow earn a high score.

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

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

The description fully covers the tool's complex behavior: return object structure, refusal reasons, source/evidence handling, and cost tradeoff versus sibling. Despite lacking an output schema, the description compensates with a detailed return format, making it 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?

The schema already covers all parameters with 100% coverage (question and its aliases). The description mentions 'fills arguments' generically but adds no specific parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly defines this tool as a hallucination-resistant answer mode that extracts answers using only tool results. It explicitly differentiates from ask_pipeworx by emphasizing grounded evidence (verbatim quote) and refusal behavior, making the purpose unmistakable.

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

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

It states exactly when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups'. It also names the alternative tool and highlights the extra LLM call cost, providing clear 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral details: resolver contract (confidence, alternatives, suggestions), parent_event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market skip, wide spread warnings), and resolution-rule risk parsing. 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 very long and detailed, covering many edge cases. While front-loaded with the main purpose, it could be more concise by moving extensive details (e.g., resolver contract, resolution-rule risk) to separate documentation. Every sentence provides value, but overall length may overwhelm agents.

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 classifiers, data sources, special cases), the description is thoroughly complete. No output schema exists, but the description explains all return fields: market (bid/ask/spread etc.), analysis (model prob, edge, kelly), evidence by source, resolver contract, parent_event, and news error handling. It covers safety and blocking conditions.

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

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

Schema description coverage is 100% (all 3 parameters documented). The description adds meaning: clarifies market parameter accepts slug, URL, or question text; explains depth options (quick vs thorough) and include_raw guidance; provides examples. Baseline 3 is elevated because description adds value beyond schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output structure (evidence packet + comparison). Distinguishes from siblings by focusing on Polymarket bets with classifier-based fan-out.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives examples for various bet types. While it doesn't explicitly list when not to use, the guidance 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 indicate safe, read-only behavior. Description adds valuable context: for companies, it pulls specific financial data from SEC EDGAR/XBRL with proper fiscal year handling; for drugs, it pulls FAERS data. Also states results are sorted by primary metric.

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

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

Two sentences, front-loaded with examples, no unnecessary words. Efficient and well-structured.

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

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

Despite no output schema, description explains return format (paired data + citation URIs) and sorting. Covers all aspects needed for an agent to use the tool correctly.

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

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

Schema covers 100% of parameters. Description enriches by detailing the 'type' options (company vs drug) and explaining 'values' format with examples (tickers for company, drug names for drug), adding meaning beyond the schema.

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

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

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one call. It specifies the verb 'compare' and the resource 'entities', distinguishing it from single-entity tools like entity_profile.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities. Provides example queries and specifies constraints (2–5 entities, one call).

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 establish readOnly/openWorld/idempotent non-destructive behavior, and the description adds substantial behavioral context: account requirements, depth tiers, facet decomposition, parallel tool routing, findings packet composition (verbatim evidence, confidence, gaps[], contradictions[]), citation_uri fetchability guarantee, semantic excerpting, and latency expectations. It also explicitly states the tool never invents answers, going beyond the schema.

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, front-loaded with the critical account requirement and core function, then usage guidance, then operational details. Some redundancy exists (e.g., 'never invented' and the gaps[] explanation), but the length is largely justified given the tool's complexity and the absence of an output schema.

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 exists, so the description fully covers return values: findings packet fields, gaps[], contradictions[], hop field, citation_uri, and latency. It also explains prerequisites, tier differences, and failure modes (empty gaps for current news). The description is self-sufficient for an agent to decide and invoke the tool correctly.

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

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

Schema description coverage is 100%, but the description enhances both parameters. For 'depth', it explains each enum value with hop behavior, gap recovery, and paid tier implications. For 'question', it clarifies that broad/multi-part natural language is expected and that decomposition is a feature, not a limitation.

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

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

The description clearly states a specific verb ('research') and resource ('Pipeworx's 1455 STRUCTURED data sources'), and explicitly distinguishes itself from open-web search and sibling ask_pipeworx. It uniquely describes its multi-source, facet-decomposition, parallel-routing behavior, making its purpose unmistakable.

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

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

The description provides explicit 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 or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives a fallback if not signed in, naming the alternative tool and tier constraints.

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, non-destructive behavior. The description adds that the tool uses OpenStreetMap data via OpenRouteService and returns geometry, distance, duration, turn-by-turn instructions, and elevation. This contextual information beyond the annotations is valuable and consistent with them.

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

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

The description is efficient, covering purpose, use cases, profiles, outputs, and data source in a single block. It is not overly verbose, though it could be slightly more structured for easier parsing. Every sentence contributes 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's complexity (routing with multiple profiles) and the presence of an output schema, the description provides essential information: input requirements, output types, profiles, and data source. It is complete enough for an agent to select and use the tool appropriately.

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 50%, with 'profile' lacking description. The description compensates by listing all profile values (driving-car, driving-hgv, foot-walking, etc.), which adds meaning. For 'instructions' and 'format', the description does not add beyond schema but is adequate. Overall, it reasonably covers the semantic gap.

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 provides turn-by-turn routing with profile-specific routing, listing various query types and outputs. It explicitly distinguishes itself from sister tools like elevation_point and matrix by mentioning special use cases (hiking, wheelchair, truck) where Mapbox/Google lack appropriate 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?

The description provides explicit use cases (hiking, cycling, wheelchair, truck routing) and recommends use when Mapbox/Google don't have the right profile. It lists all available profiles. However, it does not explicitly state when NOT to use or mention alternative tools besides the implicit reference to Mapbox/Google.

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 and idempotentHint. The description adds details about returning top-N tools with full schemas and examples, ready to call, which 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?

The description is front-loaded with the purpose and includes many examples, but is slightly verbose. Every sentence is useful, but some redundancy exists.

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

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

Without an output schema, the description carries full burden and clearly explains the return value (names, descriptions, schemas with examples), making it complete for this discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description lists parameter aliases but does not add meaningful new information 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 'Find tools by describing the data or task' and lists many domains, distinguishing it from all sibling tools which are specific data retrieval or analysis 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 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context and no ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds input format details (geojson, polyline, etc.) and usage scenarios but does not elaborate beyond the annotations' safety profile.

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

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

A single, well-structured sentence that front-loads the purpose with quoted synonyms, followed by a list of use cases. Every phrase 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?

Given the tool's simplicity (2 parameters), annotations covering safety, and an existing output schema, the description provides all necessary context: purpose, input formats, and typical applications.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explicitly listing supported geometry formats and indicating the geometry is a linestring, reinforcing the schema's format_in enum and geometry 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 states the tool provides elevation samples along a linestring geometry using verbs like 'elevation profile', 'elevation gain', and 'topographic profile'. It distinguishes from the sibling 'elevation_point' by focusing on routes vs points.

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

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

The description explicitly lists use cases: hiking elevation gain, cycling grade analysis, trail planning, terrain profiles. It does not provide exclusions or direct comparisons, but the sibling 'elevation_point' implicitly covers when not to use this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying the output unit ('meters above sea level') and the single-point constraint. 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 a single sentence with embedded examples and usage hints, fully front-loaded with the key terms. Every word is purposeful and contributes to clarity.

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

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

Given the tool's simplicity (2 parameters, straightforward purpose) and the presence of an output schema, the description is complete. It covers the main use case and parameter details sufficiently.

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 applies. The description provides example geometries and explains the 'format_in' values, but these details are also in the schema. No significant extra meaning beyond the schema.

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

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

The description clearly states the tool returns elevation/altitude at a single point, provides example queries ('how high is [location]'), and distinguishes from the sibling tool 'elevation_line' by specifying 'at a single 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 explicitly mentions use cases like 'what's the elevation of Denver', terrain queries, and attaching altitude to GPS records. It does not explicitly state when not to use, but the context and sibling list imply alternatives like elevation_line for lines.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context: patents soft-fail (USPTO API sunset), fundamentals return latest 10-K data sorted by period_end DESC, news uses GDELT→GNews fallback, and names are not supported. This goes well beyond annotations.

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

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

The description is front-loaded with example queries and a clear preference statement. It then lists all outputs and sources. While slightly verbose, each sentence earns its place due to the complexity of the tool. Could trim redundant examples but overall efficient.

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

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

Even without an output schema, the description enumerates all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and their sources. It also covers limitations (patents soft-fail, names not supported). For a profile tool, this is complete.

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

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

Schema descriptions for both parameters are clear (type enum with 'company', value as ticker or CIK). The description adds further meaning: explains why names aren't supported, mentions zero-padded CIK format, and shows example values. Schema coverage is 100%, and description compensates well.

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

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

The description explicitly states it returns a full cross-source profile of a US public company, listing specific data sources (SEC, XBRL, USPTO, news, GLEIF) and fields. It distinguishes itself from sibling tools like resolve_entity and compare_entities by stating when to prefer this over chaining single-pack lookups.

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

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

The description clearly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity first if only a name is available. This provides explicit 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 declare destructiveHint=true and idempotentHint=true. Description adds context about deleting 'memory' and clearing sensitive data, but does not disclose behavior beyond what annotations provide. No contradiction.

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

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

Two sentences, front-loaded with core purpose, no extraneous information. Every sentence earns its place.

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

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

For a simple delete tool with one parameter, complete annotations, and no output schema, the description provides all necessary information: purpose, usage guidance, and relationship to siblings.

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

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

Schema coverage is 100% and the single parameter 'key' is fully described in the schema as 'Memory key to delete.' Description adds 'by key' but no additional meaning. Baseline 3.

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

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

The description explicitly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by mentioning them as complementary.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also pairs with 'remember' and 'recall' as alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it fetches the page and emits standard llms.txt markdown, which complements the annotations without contradicting them. No additional behavioral details (e.g., rate limits, auth needs) are provided, so the description adds moderate value.

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 concise sentences. It front-loads the main action and lists use cases efficiently. A minor improvement would be to break into bullet points, but it remains clear and free of fluff.

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

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

Given the tool has only 2 parameters and no output schema, the description fully covers what the tool does, how it works, and what the output is (a text blob ready at site-root/llms.txt). It also provides use cases, making it comprehensive for an agent to determine when to use it.

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

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

Schema coverage is 100% for both parameters ('url' and 'max_links'), so the schema already documents them clearly. The description mentions 'fetches the page' (implying URL) and 'link entries' (implying max_links), but does not add new semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description explicitly states the tool generates a production-ready llms.txt file for any URL, specifying the process (fetch page, extract title/description/key links) and the output format. This clearly distinguishes it from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning presence.

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

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

The description lists concrete use cases (getting client site indexed, drafting for own project, auditing competitor) but does not explicitly mention when not to use or provide alternatives. The context signals show sibling tools exist (e.g., 'scan_competitor_ai_presence'), but no comparison is made.

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 idempotent, read-only, not destructive. Description adds that it uses Pelias, returns ranked candidates with lat/lng, address components, and layer. It does not 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 two sentences plus a list of example queries. It is relatively concise and front-loaded with purpose, though the list of examples could be shortened without loss.

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

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

Output schema exists, so return values are documented. However, with 6 parameters and no param descriptions, the description does not fully compensate. It covers the core behavior but leaves details on optional parameters unclear.

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 0% (no descriptions in schema). The description only implies 'text' and 'size' via examples, but does not explain 'layers', 'sources', 'focus_lat', 'focus_lon'. This leaves significant ambiguity.

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 geocodes an address or place name to coordinates, gives example query patterns, and explicitly contrasts with Mapbox/Google as a free OSM alternative. This distinguishes its purpose well among siblings.

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

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

The description advises use as a free alternative to Mapbox/Google or when OSM data is desired. It does not provide explicit when-not-to-use or alternative sibling tools, but the context is clear and actionable.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about using OpenStreetMap data, which is helpful. 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 a single, front-loaded sentence with a list of alternative names and use cases. No wasted words; every part 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's complexity and the presence of an output schema, the description covers core functionality, profiles, and use cases. Minor missing details (e.g., maximum range, location count limits) but still 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 50%, but the description explicitly lists profiles (car, truck, bike, foot, wheelchair) and the concept of range in time/distance. This adds meaning beyond the schema, which lacks descriptions for profile and locations.

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

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

The description clearly states the tool generates isochrone polygons (area reachable from a point) for multiple profiles using OpenStreetMap. It provides alternative names and use cases, distinguishing it from sibling tools like directions or matrix.

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 mentions use cases but does not explicitly state when to use this tool vs alternatives. No exclusionary guidance is provided; usage is implied rather than stated.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds return fields and default active-only behavior, but does not address openWorldHint.

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

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

Three concise sentences: action and scope, return fields, usage guidance. No fluff, front-loaded.

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

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

Adequate for a simple list tool with one parameter and no output schema. Covers purpose, returns, and usage context. Could mention lack of pagination but not essential.

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

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

Schema already describes the single parameter (include_inactive) with default. Description does not add further parameter semantics beyond schema.

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

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

Clearly states the tool lists the caller's active subscriptions and returns specific fields. Differentiates from siblings subscribe/unsubscribe by focusing on review and finding cancellation IDs.

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

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

Explicitly advises using this tool before adding more subscriptions or to find an ID to cancel, setting clear usage context and prerequisites.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context beyond that: it uses OpenStreetMap routing (external data source), is profile-aware (different travel modes), and implies scalability through 'N×M'. 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 compact and front-loaded: a core definition followed by use cases and profile note. The quoted aliases at the start are unconventional but serve as useful search phrases and don't add unnecessary length. Every sentence contributes 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?

With an output schema present and strong annotations, the description covers purpose, use cases, data source (OSM), and profile modes. The N×M structure and sources/destinations are explained via schema examples. Minor gaps like coordinate ordering are left to examples but do not impair understanding.

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

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

Schema description coverage is 60%: sources and destinations are well described ('NOT coordinates', 'Omit to use every location'), and metrics has allowed values. However, profile and locations lack schema descriptions. The tool description partially compensates by listing profile modes (car/truck/bike/foot/wheelchair) and examples imply coordinate format, but it doesn't explicitly define coordinate ordering.

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

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

The description clearly defines the tool as an 'N×M distance and duration matrix between many points via OpenStreetMap routing.' The quoted aliases ('all-to-all travel times', 'drive / walk / bike times') reinforce the purpose and distinguish it from siblings like directions and isochrones.

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

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

It explicitly states usage contexts: 'Use for traveling-salesman setup, multi-stop optimization, nearest-warehouse, fleet dispatch.' This gives clear when-to-use guidance, though it doesn't explicitly mention alternatives or when-not-to-use, which would earn a 5.

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

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

Annotations only signal non-read-only, non-destructive, non-idempotent. The description adds significant behavioral context: it can act as a submitter or a status-checker depending on claim_token, it returns a claim_token when filed without an account, it is rate-limited to 5 per identifier per day, it is free, and it doesn't count against tool-call quota. It also warns against pasting end-user prompts, which is a valuable behavioral guideline.

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?

Though longer than a two-sentence description, the content is dense and each sentence serves a distinct purpose: purpose, usage triggers, scope exclusions, content guidance, claim token workflow, rate limit, and cost. It is front-loaded with the primary purpose and structured logically with no redundant 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?

There is no output schema, but the description covers both operational modes (submit and check status), explains the return value (claim_token) and what subsequent calls return (status and changes), and adds constraints like rate limit and quota-free usage. This is a complete picture for a tool with this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage nuances beyond the schema, especially for claim_token (how to pass it back to read status/resolution) and for message (describe in terms of Pipeworx tools/packs, don't paste end-user prompt). This elevates it above the baseline, though the schema still carries most parameter documentation.

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 action (tell the Pipeworx team something is broken, missing, or needs to exist) and specifies the resource (Pipeworx tools served by this connection). It distinguishes from siblings by explicitly excluding tools from other MCP servers and referencing the catalog of this connection.

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 scenarios (bug, feature/data_gap, praise) and a direct when-not-to-use exclusion (tools from other MCP servers, with the alternative to file with that server). It also tells users how to disambiguate (Pipeworx tool names are those this connection lists).

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. Description adds: data source (CF analytics-engine), privacy (no PII), caching (5min-1h). 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 concise, with three clear bullet points for use cases and a single sentence for behavioral notes. No unnecessary words, front-loaded with main purpose.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers purpose, usage, data source, privacy, caching, and behavioral traits. Annotations handle safety. Complete for an agent to decide.

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?

Only one parameter 'window' with 100% schema coverage. Schema enum description already explains values; description adds behavioral nuance ('shorter windows surface hot now, longer show steady-state'), which provides extra context 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 returns trending tools, packs, and call volume over a time window. It explicitly mentions 'top tools, top packs, and total call volume', which is specific and distinguishes it from sibling tools like ask_pipeworx or search 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?

Three use cases are listed, and window selection guidance is given ('shorter windows surface what's hot right now; longer windows show steady-state demand'). However, no explicit 'when not to use' or alternative sibling comparison is 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: semantic anchor (Jaccard >=0.30), partition filter (placeholder fraction), fill check logic (theoretical vs realizable edge). No contradiction with annotations.

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

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

Description is detailed and contains technical jargon, but it front-loads key information and uses clear sectioning. Slightly verbose but efficient for the complexity.

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

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

No output schema, but the description explains the response structure (opportunities[] with fields, partition_check, fill check). Covers complex logic like Jaccard similarity, partition filter, and fill check comprehensively.

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 brief descriptions. The tool description enriches each parameter with examples, expected formats, and detailed behavior per mode, adding significant value beyond schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It explains the three modes (no args, event, topic) and distinguishes from sibling tools like polymarket_fill_risk 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also warns when not to trade (realizable_edge <= 0) and references sibling tool for custom sizing.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds substantial behavioral context: caching at KV level for 1h, response structure with diagnostics, Fed data reliability warnings, and tradeable-edge filters. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections for model families, response structure, and knobs. It front-loads the purpose. Some technical details could be abbreviated, but the complexity justifies the length.

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

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

Given 9 parameters, no output schema, and complex response, the description covers response segments (by_segment, diagnostics), caching, and edge cases (Fed data, stale markets). It ensures agents understand what to expect and how to interpret empty 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?

All 9 parameters are 100% covered by schema descriptions. The tool description adds significant value by explaining usage contexts, default values, and trade-offs (e.g., slippage_pp explains Polymarket fee structure, min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs).

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

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

The description clearly states the tool scans Polymarket markets and identifies opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage, polymarket_edge_tracker, etc., by focusing on edge discovery across three model families.

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

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

The description explicitly frames the tool for 'what should I bet on today' discovery and explains when to use it via the tradeable-edge knobs and filter defaults. However, it does not directly compare with siblings or state when not to use it.

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

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

Annotations already indicate readOnly, idempotent, etc. The description adds behavioral details: data source (daily snapshots), possible gaps, response structure, and computation method. 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 with information but well-structured: opening statement, parameter details, response format, and limits. Could be slightly more concise, but every sentence serves a purpose.

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

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

Given complexity and no output schema, the description fully explains return structure (tracked, expired, snapshot_dates), data sources, limitations, and computation details. An AI agent has all needed context to invoke correctly.

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

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

Both parameters are described in the schema (100% coverage). The description adds default values, clamp ranges, and context about window families and snapshot triggers, enhancing understanding beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and shrinkage. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explicitly states when to use: to evaluate if an edge is fresh or old, and contrasts the implications. It provides limits (60-day TTL, snapshot start date) but does not explicitly name alternatives for 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it walks the order-book ladder, returns verdicts (clean/degraded/cannot_fill), explains how partial basket fills convert arb into directional risk (the dominant loss mode), and names 'thin_legs' and 'forced_directional_risk'. This goes well beyond the annotation 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 verbose (200+ words) but well-structured with clear section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, but some could be tightened. The front-loading of the core purpose and mode requirements is excellent, making it easy to scan.

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

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

Despite no output schema, the description fully explains the return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict; for basket: theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers edge cases like partial fills and directional risk, making it complete for this 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 rich semantic meaning: it explains how parameters like side and size_usd behave differently in single-market vs. basket modes, provides defaults and constraints, and clarifies the interpretation of size_usd (max spend vs. target proceeds vs. settlement notional). This goes far beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with specific verbs and outcomes, and it stands apart from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool (before acting on those signals).

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills create directional risk) and delineates when not to use it by omission (e.g., for small trades). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral details: the two modes, response fields (leg-by-leg prices, matched spreads, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and the meaning of compatibility scenarios. This fully informs the agent of edge cases and result interpretation.

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 bold headers (TWO MODES, RESPONSE, SAFETY FIELDS) and flows logically. However, it is somewhat verbose, particularly the safety fields section with extensive enumeration of counter fields. Concision could be improved without losing key information.

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

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

Given no output schema, the description thoroughly covers the response structure, safety warnings, and edge cases (temporal alignment, skipped comparisons). It explains how to interpret spread validity, which is critical for an arb signal tool. The description is comprehensive given the tool's complexity and three parameters.

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?

All three parameters have schema descriptions with 100% coverage. The description reiterates the topic list and modes but does not add new semantics beyond what the schema already provides. The examples in the schema further aid understanding, so the description adds marginal value.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, specifies the two modes (topic and explicit), and describes the response structure. It distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing cross-venue analysis.

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

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

The description provides explicit guidance on when to use each mode, lists the pre-mapped shortcuts, and warns that most pre-mapped topics return compatibility warnings. However, it does not explicitly state when to prefer alternative tools (e.g., polymarket_arbitrage) over this one, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: the tool retrieves saved values, can list keys, and is scoped to an identifier. It does not contradict annotations and provides additional behavioral details beyond them.

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

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

The description is four sentences, each providing distinct value: purpose, usage examples, scope, and pairing. No redundant words, and the essential information is front-loaded.

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

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

Despite no output schema, the description explains what is returned (value or list of keys) and covers scope and pairing. The tool is simple with one optional parameter, and the description is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds behavioral context by explaining that omitting the key lists all saved keys, which reinforces and clarifies the parameter's behavior beyond the terse schema description.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys' with a specific verb and resource. It distinguishes from siblings by mentioning remember (save) and forget (delete).

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

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

The description provides explicit usage context: 'look up context the agent stored earlier... without re-deriving it from scratch', examples of what to retrieve, and the scope ('Scoped to your identifier'). It implies when to use (when needing previously stored info) and alternatives via sibling references.

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 and destructiveHint false. The description adds behavioral details such as return fields, filtering options, and mark_read side effect, enhancing 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 concise, front-loaded with the core action, and every sentence adds value without redundancy. It efficiently conveys key information.

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

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

Given 5 parameters, 100% schema coverage, and no output schema, the description adequately covers the tool's purpose, filtering, side effects, and alternative access. It could mention ordering or pagination, but it's sufficiently complete for a read-only list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context for 'type', 'since', and 'mark_read' but does not elaborate on 'limit' or 'unread_only' 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 pulls fired events from the subscription feed, with a specific verb ('pull') and resource. It does not explicitly differentiate from sibling tools, but the sibling list is diverse and unrelated, so the tool's purpose is distinct.

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

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

The description provides context for usage, including when polls work and an alternative endpoint for scripts/dashboards. It explains the mark_read parameter's effect. However, it does not explicitly state when not to use this tool.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the fan-out to multiple external APIs (SEC EDGAR, GDELT, GNews, USPTO), the fallback mechanism, and the PatentsView sunset issue (soft-fail). It also outlines the return structure (changes[] grouped by source, total_changes count, citation URIs). No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is efficiently structured, front-loaded with example queries that immediately convey purpose. Every sentence serves a purpose (sources, fallback, date formats, return structure, sibling differentiation). It is somewhat lengthy but justified by the tool's complexity.

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

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

Given no output schema, the description fully covers the return structure (changes[] by source, total_changes count, citation URIs). It addresses multiple data sources, fallback logic, date format options, and a known limitation (PatentsView sunset). This is comprehensive for a tool with 3 parameters and moderate 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% (all parameters described). The description adds value by providing usage examples for the `since` parameter (ISO date and relative shorthand like '7d', '30d', '3m', '1y') and explaining that `value` can be a ticker or CIK. It also suggests typical monitoring window ('30d' or '1m'). This goes beyond the schema's minimal 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 defines the tool's purpose with specific verbs and resources: 'change feed for a company in the last N days/weeks/months'. It provides example queries ('What's new with X', 'latest on Y') and lists the data sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from sibling tool 'entity_profile' by specifying a different use case.

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

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

The description gives explicit guidance on when to use this tool vs. an alternative: 'Use entity_profile instead when you want the static profile...' It also explains fallback behavior (GDELT→GNews). However, it does not explicitly state when not to use this tool beyond the sibling comparison, but the context is clear.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context: authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradiction. Minor gap: does not mention overwrite behavior explicitly, but idempotent hint covers that.

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, then gives usage guidance, then behavioral notes. It is efficient with no wasted words, though it could be slightly more concise (e.g., 'across this conversation or across sessions').

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, and the description does not explain what the tool returns (e.g., success message, error handling). For a simple key-value store, the description covers usage and behavior adequately, but the lack of return value information is a noticeable gap.

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

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

Schema description coverage is 100% (both key and value have descriptions). The tool description adds examples of key formats and clarifies value is any text, but this does not significantly extend beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses specific verbs ('save data to reuse later') and clearly identifies the resource (key-value store). It distinguishes from siblings by naming recall and forget, making the tool's purpose unmistakable.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and provides concrete examples. It also mentions pairing with recall and forget, offering clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds substantial behavioral context: identifier sources (SEC EDGAR, GLEIF, OpenFIGI), explicit 'unresolved' handling, graceful degradation when enrichment sources are unavailable, and internal cascading of multiple lookup endpoints. No contradiction with annotations.

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

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

The description is lengthy but well-structured: example queries, core purpose, usage directive, and detailed type-specific sections. Some redundancy exists (e.g., 'using resolve_entity replaces 2-3 manual lookups'), but for a tool with two distinct modes and rich behavior, the density is largely justified. Not ideal minimalism but acceptable.

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 fully compensates by detailing return contents (identifiers, source labels, unresolved list), input variations, error handling (graceful degradation), and internal cascade. It covers both company and drug modes comprehensively. Given the tool's complexity, the description is complete enough for confident 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?

Even with 100% schema coverage, the description significantly enriches parameter semantics. It explains what inputs are accepted for 'company' (ticker, CIK, or name) and 'drug' (brand or generic), what identifiers are resolved, and how each source contributes. It also clarifies output behavior (e.g., unresolved listed explicitly), exceeding the schema's terse parameter descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with explicit examples ('ticker for', 'CIK for'). It distinguishes itself from siblings by positioning as a prerequisite for other tools ('identifiers other tools require as input') and gives a strong directive: '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?

Explicitly states when to use: 'Use FIRST whenever you have a name but need an ID.' Provides concrete example queries to trigger usage. Notes it replaces 2-3 manual lookups, implying efficiency. While it doesn't name specific alternatives, it gives clear contextual guidance for when this tool is appropriate.

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

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

The description discloses that it probes each entity with ai_visibility_check, a read-only operation consistent with annotations (readOnlyHint, idempotentHint). It adds behavioral context about returning a ranked list with score, confidence, and signal density, beyond what annotations provide.

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

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

The description is a single concise paragraph of four sentences, front-loaded with the core purpose and efficiently packed with all necessary information without any fluff.

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

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

Despite no output schema, the description fully explains the return value (ranked list with score, confidence, signal density per entity). All input parameters are covered in the schema, and the description adds necessary context for usage. The tool's complexity is well-addressed.

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

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

Schema coverage is 100%, and the description adds critical semantic information: the first entity is treated as the 'subject' for narrative and rest as competitors. It also provides context for models and _apiKey parameters, enhancing understanding beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using verbs like 'Compare', 'Probes', 'ranks', and 'surfaces'. It distinguishes from sibling tools by explaining it is a batch version of ai_visibility_check, and provides a concrete example.

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 specifies it is useful for competitive AI-marketing audits and gives an example question. It implies when to use, but does not explicitly state when not to use or name alternatives, though the presence of ai_visibility_check as a sibling provides implicit 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?

Beyond annotations (readOnly, idempotent, openWorld), the description adds behavioral details: fans out across deps.dev and bundlephobia, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 verbose but every sentence adds value. It front-loads the core purpose and then details behaviors and limitations. Could be slightly more concise, but remains well-structured and informative.

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

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

Despite no output schema, the description thoroughly outlines the return structure (summary block with fields, per-advisory detail, links, recent alternative versions). It covers usage, behavioral traits, and error handling (partial failures, timeout), making it complete 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 coverage is 100% for both parameters. The description adds extra context: for 'package' it mentions scoped packages are accepted, and for 'version' it notes defaults to latest when omitted. This adds value beyond the schema's basic 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 it is a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying the npm ecosystem and referring to other ecosystems (PyPI, Maven, etc.) that should use deps.dev directly.

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

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

Explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies limitations: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly', providing clear alternatives.

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

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

Discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation, and character offsets.

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 that are front-loaded and contain no fluff; 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?

Covers input, behavior, and output hints (passages with offsets and scores); could mention output format but still adequate for a 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?

Schema coverage is 100%, but description adds context like max character count and natural-language query examples, plus underlying mechanics not in 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 it performs semantic search inside a fetched record using specific verb and resource, and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use (record too big for prompt) and pairs with a sibling tool, but doesn't list alternative tools 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 declare readOnlyHint=true and destructiveHint=false. Description adds context about profiles (car/bike/foot) and use cases. No contradictions. Describes behavioral traits beyond annotations.

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

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

Extremely concise: one sentence with parenthetical alternatives and use cases. Front-loaded with key verb and resource. 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?

With annotations and output schema, description covers purpose, usage, key parameters, and use cases. No gaps given tool 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 description coverage is 0%, but description explains 'profile' parameter with examples and implies 'locations' are GPS coordinates. Output schema exists. Description adds meaning beyond bare 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 'Snap coordinate to nearest road' and provides alternative phrasings. It specifies the verb (snap), resource (coordinates to road), and distinguishes from sibling tools like 'directions' and 'geocode_search'.

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

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

Explicit use cases: 'clean noisy GPS, validate routability before calling directions, or place markers on a road network.' It implies when to use but does not explicitly state when not to use or provide 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 indicate idempotentHint=true, openWorldHint=true, but the description adds valuable context: returns a new subscription id, requires OAuth, per-type and delivery specifics. 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 front-loaded with purpose, then types, then delivery. It is detailed but every sentence is informative; slightly lengthy but justified by complexity.

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

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

Given 3 parameters (2 required) and no output schema, the description fully covers return value (subscription id), type-specific params, delivery constraints, and prerequisites, leaving no gaps.

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

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

Despite 100% schema coverage, the description adds rich examples for each type and delivery option, including webhook HMAC signing details, far exceeding the schema's brief property 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 uses a specific verb-resource pair ('Create a proactive monitoring subscription to a live-data event stream') and clearly distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides extensive context on when to use (requires OAuth account, supported types with examples, delivery channels) but does not explicitly mention when not to use or name alternatives.

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

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

Annotations already convey safety (readOnly, idempotent, non-destructive). The description adds behavioral context: returns categorized examples with exact tool+argument shapes, and can be called with no args or topic. 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 thorough and well-organized, with examples of triggering phrases and a clear list of topics. Every sentence adds value, though it could be slightly tightened without loss.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete: it explains what the tool returns, when to use it, and how to parameterize. No gaps remain.

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

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

Schema coverage is 100% with a description for the single parameter. The description adds value by explaining what each topic value means and that omission yields a full spread, going beyond the schema's short 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 states the tool's purpose: it returns category-bucketed example questions for onboarding an agent that just connected. It uses specific verbs ('returns', 'use this FIRST') and distinguishes from sibling tools like ask_pipeworx by explaining this is for learning what Pipeworx can do.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and mentions optional topic parameter to focus. This provides clear when-to-use and alternative guidance.

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

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

Description adds behavioral detail beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts'. Aligns with annotations (destructiveHint=false, idempotentHint=true). No contradiction.

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

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

Two efficient sentences: first states action and ownership, second explains effect. No unnecessary words. Front-loaded with key info.

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 (1 param, no output schema), description covers purpose, ownership, and behavioral effect. Adequately 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% and description of 'id' parameter ('Subscription id (uuid) returned by subscribe') adds minimal extra meaning beyond the schema definition. Baseline score of 3.

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

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

Description explicitly states 'Cancel a subscription by id', which clearly identifies the action and resource. It differentiates 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?

Ownership enforcement is clearly stated: 'you can only cancel your own subscriptions'. No explicit when-not or alternatives, but the constraint provides clear usage 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral context: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source exists), plus the structured vs. grounded pipeline behavior. This is valuable transparency not present in annotations.

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

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

The description is relatively long but information-dense, with a clear front-loaded intent and structured flow from purpose to usage to outputs and important caveats. Every sentence earns its place; the length is justified for a tool with this complexity. Minor redundancy exists in repeating the verification concept.

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

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

Given the tool's complexity and the absence of an output schema, the description fully compensates by detailing return values (verdicts, actual value, citation, reasoning) and error semantics. The annotations handle safety, and the description covers operational nuances, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant extra meaning about parameters beyond the schema's own descriptions; it mentions 'exact percent-delta math' and tolerance overriding, but these are implied in the schema. No additional parameter detail is provided, so a 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' and provides specific verb patterns like 'fact check' and 'verify the claim that…'. It distinguishes from siblings by explicitly covering two routing paths (SEC EDGAR for financial claims, grounded pipeline for others) and noting it replaces 4–6 sequential calls, making its scope unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the fallback behavior for non-financial claims. It does not explicitly name alternative tools for when not to use it, but the guidance is strong and contextually clear.

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