Osrm

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds cost implications (free vs. paid Anthropic calls) and return structure (per-model scores with confidence, signals, raw_response). 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 three sentences, front-loaded with the core purpose. Every sentence adds value: purpose, default vs. API key, return format, and use cases. No redundancy or fluff.

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

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

No output schema, so the description adequately explains return values per model and combined view. Parameters are all covered with practical notes (e.g., context disambiguation). For a 4-parameter tool with 1 required, the description is complete and actionable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains that _apiKey is for Anthropic and passed directly, that context disambiguates entities, and that models defaults to workers-ai. This extra context elevates the score.

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

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

The description clearly states the tool probes LLMs for entity knowledge and produces visibility scores per model. It specifies the default model and optional Anthropic probe, differentiating it from sibling tools like scan_competitor_ai_presence. The verb 'probe' and resource 'LLMs' with scoring make the purpose specific and unambiguous.

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

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

The description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use or name alternatives, but the context is clear enough for appropriate selection. A minor gap in excluding inappropriate scenarios.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. Description adds context about how it routes to thousands of sources, fills arguments, and returns structured answers with citations. 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?

Front-loaded with key instruction, then organized into use cases, examples, and disclaimers. Slightly verbose but 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?

For a query tool with no output schema, description explains behavior, expected results (structured answers with citations), and provides extensive examples. Covers usage context and limitations.

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

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

Schema coverage is 100%, so baseline is 3. The description provides examples of questions but does not add significant parameter-level detail beyond the schema.

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

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

Description uses specific verbs like 'routes', 'fills arguments', 'returns structured answer', and lists extensive domains. Clearly differentiates from siblings like ask_pipeworx_grounded and deep_research.

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 'PREFER OVER WEB SEARCH' and provides detailed when-to-use scenarios with examples. Also advises when to use alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad questions).

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?

Builds on annotations by detailing the experimental source-preference ranking behavior and clarifying it is a full working router, not a fallback. The description adds useful context beyond what annotations provide, such as the 'source-preference ranking' mechanism.

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 efficiently convey purpose, key experimental feature, usage instructions, and fallback behavior. No redundant or unnecessary text; 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?

For a beta tool with experimental features and no output schema, the description covers all essential aspects: what it is, what it shares with the stable version, the specific improvement, usage guidance, and its standalone nature. Fully sufficient for an agent to decide 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?

The input schema already provides complete coverage for all 6 parameters with descriptions. The description mentions 'same arguments' but adds no new semantic detail beyond what the schema offers, meeting the baseline for high schema coverage.

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

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

Clearly identifies the tool as a beta version of ask_pipeworx with identical routing capabilities but an experimental source-preference ranking feature. Distinguishes from its sibling ask_pipeworx by specifying the new behavior and the context for use.

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 to use it 'exactly like ask_pipeworx when you want the newest routing' and that results are compared against the stable router. Does not explicitly list when not to use, but provides clear guidance for the intended use case.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals key behaviors: picks the right tool from 5,008 across 1,318 sources, fills arguments, fetches data, extracts answer using ONLY tool result, and details return format with evidence and refusal reasons. 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 appropriately sized with all sentences adding value. It front-loads the key purpose and differentiation. Slightly verbose but 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?

Given the tool's complexity (multiple sources, routing, extraction, refusal reasons), the description is comprehensive. It explains the internal process, output format, error modes, and usage context. No output schema exists, so description adequately covers return values.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for 'question'. The description does not add new semantic information beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads,' specifies the verb (extract answer), resource (Pipeworx tool ecosystem), and distinguishes it from the sibling ask_pipeworx by highlighting the extra extraction step and cost. It also details the structured output format.

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 answers will be quoted, cited, or acted on, and for domains like financial verdicts, legal claims, medical lookups, public statements. Also provides when-not-to-use guidance: prefer ask_pipeworx for casual lookups, and mentions cost trade-off.

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 extensive behavioral context beyond annotations: it explains resolution, classification, fan-out, response shapes (market, analysis, evidence), resolver contract, parent_event extractor, news fallback, safety checks (low-confidence, closed markets, wide spreads), and resolution-rule risk. Annotations already indicate safe, read-only, idempotent behavior, and the description enriches this with specific operational details. 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?

The description is excessively long and poorly structured—it is a single dense paragraph with no bullet points or sections. While every sentence adds value, the verbosity and lack of organization hinder quick scanning. An AI agent would benefit from a more structured format to locate key information efficiently.

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

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

For a complex tool with 3 parameters and no output schema, the description covers input resolution, classifier categories, fan-out logic per category, response shapes, resolver confidence, parent_event extraction, news fallback, safety overrides, and resolution-rule risk. It even notes practical edge cases like GDELT 429s and closed market indexation. The description is exceptionally complete for this complexity level.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds significant value by explaining how the 'market' parameter resolves different input types (slug, URL, question text) and by clarifying the 'depth' and 'include_raw' parameters with practical advice (e.g., 'quick = 2-3 evidence sources' and 'when false (recommended)...'). This elevates the score above baseline.

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

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

The description opens with a clear statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explicitly states the verb (research), resource (Polymarket bet), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on evidence aggregation. The description also provides usage examples and classifies bet types, leaving no ambiguity about the tool's purpose.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-out and classifiers, giving context. However, it does not explicitly state when not to use or suggest alternative tools, which would improve clarity. Nonetheless, the guidance is clear and contextual.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds meaningful behavioral context: single parallel call, handles off-calendar fiscal years for companies, returns paired data with citation URIs, and replaces 8-15 sequential lookups. 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?

Description is somewhat lengthy but every sentence adds value, covering what data each type returns, edge cases (off-calendar years), and return format. Front-loaded with example queries. Could be slightly more concise, but appropriate for the tool's complexity.

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

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

Given no output schema, description adequately explains what is returned: paired data, citation URIs, and sorting by primary metric so top results align with 'largest'/'most'. Covers edge cases (e.g., different fiscal year ends) and provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%. Description significantly enriches parameter meaning: explains that 'type='company'' pulls specific financial metrics from SEC EDGAR/XBRL with correct handling of fiscal years, while 'type='drug'' pulls adverse events, approvals, and trials. Provides examples and constraints for 'values' array.

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?

Title and description clearly state the tool compares 2-5 companies or drugs side-by-side. Provides specific examples like 'which is bigger' and 'rank these companies', and distinguishes it from sequential lookups by specifying it performs a single parallel call.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear guidance on when to use. Examples of queries cover various comparison types. Does not explicitly list when not to use, but context implies it's only for comparisons.

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?

Describes extensive behavioral details: expected timing (15-90s), account/auth requirements, return format (findings with citations, gaps, contradictions, hop field), iteration behavior per depth, and handling of large records. No contradiction with annotations (readOnlyHint, openWorldHint, 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?

Description is long but dense with valuable information. It is front-loaded with critical account requirement and alternative tool. Every sentence serves a purpose, though minor trimming could improve readability. Still, given the complexity, the length is justified.

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 format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It also covers timing, iteration, large record handling, and when results may be empty. Comprehensive for the tool's complexity.

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

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

Schema coverage is 100% (both question and depth are described). Description adds significant meaning: explains depth enum values (quick=3 facets, standard=5+gap recovery, thorough=8+iterative+contradictions) and clarifies that question should be broad/multi-part. Goes well beyond schema definitions.

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 'grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources' and distinguishes itself from sibling ask_pipeworx by noting it uses parallel tool routing and is not for single lookups or breaking news. The verb 'research' and resource 'structured data sources' are specific.

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 deep_research (broad/multi-part questions over structured data) and when not (single lookup -> ask_pipeworx; breaking news -> ask_pipeworx). Also mentions account requirements and paid plan for 'thorough' depth, with alternatives for unsigned users.

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, non-destructive. The description adds context about return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' 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 compact (5 sentences), front-loaded with purpose, then usage, then return details. No fluff, each sentence adds value.

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

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

Despite no output schema, the description thoroughly explains what is returned and why it's useful (ready to call directly). It covers purpose, usage, and output format adequately for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting aliases for query ('Accepts task, q, description, search as aliases.') and the default/max for limit, which are already in schema but reinforced concisely.

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: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from siblings by being a discovery tool, not a task-specific tool.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use by contrasting with 'not just one answer.'

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, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: lists data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes USPTO sunset in May 2025, and describes soft-fail behavior. 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?

The description is a single paragraph that packs all necessary information. It is front-loaded with example queries. While comprehensive, it sacrifices a bit of conciseness for completeness, but every sentence adds value.

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

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

Given the tool's complexity (multiple data sources, varied returns), the description is remarkably complete. It enumerates all returned fields, provides URIs, mentions deprecations, and covers fallback behavior. No output schema exists, so the description fully carries the burden.

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 crucial meaning beyond the schema: clarifies that 'value' accepts ticker or zero-padded CIK, explicitly says 'names not supported,' and notes that only 'company' type is currently available.

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: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple user query examples and distinguishes itself from single-source lookups 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and specifies that names are not supported, directing users to 'use resolve_entity first.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and the purpose of the deletion, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded with the action, no wasted words. Every sentence adds value.

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

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

For a simple delete operation with one parameter and no output schema, the description covers purpose, usage context, and references related tools perfectly.

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

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

The single parameter 'key' is fully described in the schema with 100% coverage. The description only mentions 'by key', adding no extra semantic 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 'Delete a previously stored memory by key', specifying the verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit guidance on when to use ('context is stale, task is done, or clear sensitive data') and mentions the related tools '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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetching the page, extracting elements, and emitting standard markdown. This supplements annotations well, though edge cases like fetch failures aren't covered.

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: four sentences covering purpose, method, output, and use cases. No redundancy, front-loaded with key 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?

Given no output schema, the description adequately explains the return value (text blob). It mentions standard format and placement, which is sufficient. However, it doesn't specify behavior on errors or malformed URLs, which would make it more complete.

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

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

Schema description coverage is 100% with clear parameter descriptions. The tool description reinforces the purpose of the url parameter but doesn't add new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, with specific actions (fetches page, extracts title/description/links) and output format. It's unambiguous but doesn't explicitly distinguish from sibling tools like ai_visibility_check, so score 4.

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 (client indexing, personal projects, competitor auditing) that guide when to use this tool. It doesn't mention when not to use it or alternatives, but the provided contexts are helpful.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying return fields and the include_inactive parameter effect, aligning with annotations without contradiction.

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

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

Two concise sentences: first states purpose and output, second provides usage guidance. No filler words; 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 list tool with no output schema, the description compensates by listing return fields. Parameter is fully documented in schema. Usage guidance is provided. Complete enough.

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

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

Schema coverage is 100% with a clear description for the single parameter (include_inactive). The tool description does not add further parameter semantics, but the schema already suffices.

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

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

The description clearly states the tool lists active subscriptions of the caller, specifying the resource and scope. It also enumerates return fields (id, type, params, etc.), distinguishing it from subscribe/unsubscribe 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 explicitly advises using this tool to review current subscriptions before adding more or to find an ID to cancel. While it doesn't explicitly say when not to use it, the guidance is strong and context-aware.

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 underlying service (OSRM), that it returns 'matched route geometry and confidence', and how radiuses are applied per-point. 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 sentence of about 30 words, front-loaded with the core action, and contains no redundant information. Every part is 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?

The description explains the input format, optional radiuses, and mentions the return type (geometry and confidence). Given the presence of an output schema (not shown), this is nearly complete, but a brief note on the profile parameter would improve it.

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

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

Schema coverage is low (33%), and the description explains that coordinates are 'semicolon-separated lon,lat pairs' and radiuses are 'per-point search radius in meters'. However, the 'profile' parameter is not explained, leaving ambiguity about possible values (e.g., car, bike).

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 ('Map-match') and resource ('noisy GPS trace to road network via OSRM'), and distinguishes from sibling tools like 'route' by focusing on noisy GPS trace matching rather than simple routing. It also specifies input format and optional radiuses.

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

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

The description clearly indicates this tool is for map-matching a GPS trace. Although it does not explicitly state when not to use it or mention alternatives, the context is sufficient for an AI agent to understand its primary use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so the description does not need to reiterate safety. It adds no additional behavioral context 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 sentence with no wasted words, front-loading the primary action. However, its brevity omits helpful clarifications.

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 4 parameters and low schema coverage, the description should provide parameter hints. It does not, leaving the agent underinformed. Having an output schema does not excuse the lack of input parameter context.

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

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

With schema description coverage at only 25% (only 'number' has a description), the tool description fails to add any meaning for latitude, longitude, or profile. It repeats no parameter info, thus does not compensate for the low coverage.

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

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

The description uses the specific verb 'snap' and resource 'single point to the nearest road segment', clearly stating the tool's action and object. It distinguishes from sibling tools like 'route' which involve multiple points for navigation.

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

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

The description implies usage for a single point, but does not explicitly state when to use this tool vs alternatives. No exclusions or preconditions are mentioned.

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

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

Beyond annotations (all false), the description discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that team reads digests daily. No contradictions with annotations.

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

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

The description is concise, front-loaded with purpose and usage, and every sentence adds value. No redundancy.

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

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

For a simple 3-parameter tool with no output schema, the description fully covers purpose, usage, behavioral constraints, and parameter semantics, leaving no gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the enum values (bug, feature, etc.) and providing formatting guidance for message and context, justifying a 4.

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

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

The description clearly states the tool sends feedback to the Pipeworx team, enumerates specific use cases (bug, feature, data_gap, praise), and differentiates it from sibling tools by being the sole feedback channel.

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 specifies when to use the tool (e.g., for wrong/stale data, missing tools, or praise) and what to avoid (pasting end-user prompts). Also provides rate limits and traffic free status.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds value by explaining data source (CF analytics-engine), privacy (no PII), output format (pack, tool, count), and caching behavior (5min-1h). 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 front-loaded with the main purpose, followed by three bulleted use cases, and then technical details. Every sentence earns its place with no fluff. It is concise yet 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?

Given one optional parameter, rich annotations, and no output schema, the description covers purpose, use cases, data source, caching, and privacy. It provides sufficient context for an agent to decide when to use this tool.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning beyond the schema by explaining how different windows affect results (hot right now vs. steady-state). This extra context justifies a 4.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, using a specific verb ('returns') and resource. It distinguishes from siblings by focusing on trending/popularity, which is distinct from query tools like ask_pipeworx.

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

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

The description lists three explicit use cases (discovering hot data, confirming popular tools, aligning with agent needs) and explains the window parameter's effect. While it doesn't explicitly mention when not to use or list alternatives, the context is clear and actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals key behaviors: market scanning, monotonicity checks, partition_sum validation, placeholders filtering, semantic similarity threshold, and fill check that may indicate unrealizable arb. No contradiction with annotations.

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

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

The description is comprehensive yet well-structured: core purpose first, then mode explanations, then detailed sub-checks. Every sentence adds value. Despite length, it is efficiently organized and easy to parse.

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 explains output structure (opportunities array, partition check object) despite no output schema. It covers edge cases (placeholders, semantic anchor, fill check) and references sibling tool for further detail, making it complete for a complex tool.

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

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

Both parameters are fully described in schema (100% coverage) and description adds significant context: examples of event slugs, seed questions for topic, and usage patterns. The description clarifies the semantic difference between event and topic mode beyond schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes modes (no args, event, topic) and explicitly differentiates from sibling polymarket_fill_risk by directing custom sizing to it.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for a specific market, topic for cross-event scan. It also advises against trading when fill check shows realizable edge ≤0 and directs to polymarket_fill_risk for custom sizing, clearly delineating 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 readOnly, openWorld, idempotent, non-destructive. The description adds valuable context such as 1-hour KV-level caching, response structure segments, diagnostic fields, and filtering details. 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 dense, lacking structural elements like bullet points or line breaks. The first sentence is clear, but the rest is a wall of text that an AI agent may find hard to parse quickly.

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

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

Given the tool's complexity (9 parameters, three model families, detailed response structure), the description is comprehensive. It explains caching, diagnostics, and response top-level fields. Missing sibling differentiation and output schema limit completeness slightly.

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 good parameter descriptions. The tool description does not repeat parameter details extensively but provides contextual usage hints (e.g., tradeable-edge filters). This adds moderate value beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and specifies the three model families. However, it does not differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', leaving ambiguity about when to use this specific tool.

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

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

No explicit guidance on when to use this tool versus alternatives. The phrase 'Built for "what should I bet on today"' implies a broad use case, but no when-not-to-use or sibling references are provided.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context: it explains that snapshots are written on cache-miss (explaining gaps), decay computation uses daily closes of edge_pp_net (not intraday), and history is bounded by 60-day TTL. No contradiction with annotations.

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

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

The description is well-structured, starting with purpose, then output fields, then limits. It is dense with useful information but somewhat long. Every sentence adds value, though a slight tightening could improve conciseness.

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 comprehensively explains return values: tracked[] (with full time-series, first_seen, trend, decay_pp_per_day), expired[] (with lifespan_days), and snapshot_dates[]. It also covers limits (60-day TTL, daily data, not intraday) and data caveats (gaps mean no scan). This is highly complete for a telemetry tool.

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

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

Schema description coverage is 100% (both 'days' and 'window' have descriptions). The description adds meaning by specifying default values (14 for days, '1wk' for window), clamping (2-30 for days), and explaining that 'window' refers to a snapshot family with examples. It also contextualizes the parameters within the output structure.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explains what it answers and distinguishes itself from siblings like 'polymarket_edges' by focusing on historical persistence. The verb 'tracks' implies ongoing analysis, and the resource 'edge persistence and decay' is specific.

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

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

The description implies usage for analyzing how long an edge has existed and its decay trend, but it does not explicitly say when to use this over alternatives like 'polymarket_edges' or 'polymarket_arbitrage.' No exclusions or when-not-to-use guidance 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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: it walks the ladder, returns fill quality metrics (slippage, shares filled, verdict), and for basket mode warns about forced directional risk. This context enriches the agent's understanding beyond the structured annotations, with 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?

The description is dense and front-loaded with requirements and modes. Every sentence adds value, but it is slightly verbose (≈250 words). Minor trimming could improve conciseness 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?

Despite no output schema, the description thoroughly explains return fields (top_of_book, vwap_fill_price, etc.) and covers both modes, edge cases (thin_legs), and risk warnings. It also mentions the size_usd clamp. This makes the tool's behavior fully understandable for safe invocation.

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

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

Schema description coverage is 100%, but the description adds critical meaning: relationships between market/event, default values, interpretation of size_usd per mode, and auto-detection of basket side. This supplements the schema, aiding correct parameter selection.

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 does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market and basket) and directs usage before specific sibling tools (polymarket_arbitrage, polymarket_edges), 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?

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (partial fills turn arb into directional position), effectively guiding the agent on timing and alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by detailed behavioral descriptions: modes, safety fields (compatibility_warning, temporal_alignment), counters for skipped comparisons, and the caveat that real spreads are rare. No contradictions.

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

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

The description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though slightly verbose.

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

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

Given no output schema, the description thoroughly explains the response format (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers all necessary contextual information.

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

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

Schema coverage is 100% and description adds meaning by explaining the topic shortcuts list, overriding behavior, and providing examples. Adds significant value beyond 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 explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Describes two modes (topic shortcuts and explicit custom pairings) and warns that most pre-mapped topics return compatibility warnings. Provides clear guidance on when each mode 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds essential behavioral context: scoping to identifier (anonymous IP, BYO key hash, account ID) and pairing with remember/forget. 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?

Two sentences, front-loaded with core purpose. Every sentence adds value: first states primary function, second provides usage context and pairing. No wasted words.

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

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

Despite no output schema, description adequately implies return value (saved value or list of keys). Covers scoping, pairing with other tools, and behavioral nuances. Complete for a read-only retrieval 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%, but description adds crucial meaning: 'omit the key argument to list all keys'. This clarifies the behavior beyond the schema's 'optional' designation, and gives examples of key usage.

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 retrieves values saved via 'remember' or lists all keys when omitted. Verb 'retrieve' and 'list' with resource 'saved value/keys' is specific. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says use to look up context stored earlier, with concrete examples (ticker, address, notes). Implies alternative when not to use (if nothing saved) and pairs with remember/forget. Provides clear context for when to invoke.

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 claims mark_read:true flags events as read, implying state modification, but annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. This is a direct contradiction.

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

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

Three sentences, front-loaded with core purpose, no wasted words. Each sentence adds necessary context.

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 key return fields, filtering, and side effect of mark_read. With annotations covering safety, it's mostly complete, though unread_only parameter is not explained.

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

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

Schema coverage is 100%, but the description adds meaningful detail on type, since, and mark_read parameters beyond the schema descriptions, including an example for type.

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

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

The description clearly states the verb 'Pull' and resource 'fired events from your subscription feed.' It distinguishes from siblings like 'list_subscriptions' which handles subscriptions, not events.

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 notes 'Polls work fine' and provides alternative access via HTTP endpoint, offering good context. However, it does not explicitly compare with sibling tools or state when not to use it.

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

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

Annotations already cover safe/idempotent traits. The description adds significant behavioral context: fans out to three sources, fallback logic, soft-fail for USPTO, return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions.

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

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

Well-structured with example queries upfront, but slightly verbose with multiple fallback details. Could be tightened without losing 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?

Despite no output schema, the description explains the return structure (grouped changes, count, citation URIs) and limitations (USPTO soft-fail). For a complex multi-source tool, this is thorough.

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 all three parameters (100% coverage). Description adds value by providing shorthand examples for 'since' and mentioning ticker/CIK for 'value', but the baseline is adequate without it.

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

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

The description uses specific phrases like "change feed for a company" and lists example queries ("What's new with X", "updates on Acme"), clearly stating the tool's function. It distinguishes from sibling tool entity_profile by explicitly recommending that for static profiles.

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

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

Provides explicit usage examples and conditions (e.g., "What's new with X"), and includes when-not-to-use by directing to entity_profile for static profiles. Also explains fallback behavior between GDELT and GNews.

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 non-readOnly, non-destructive, idempotent. Description adds critical behavioral context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Four sentences, each earning its place: purpose, when to use, storage details, pairing. Front-loaded with main intent. No redundancy or fluff.

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

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

Covers purpose, usage, lifecycle, and pairing. Lacks explicit mention of return value (e.g., success confirmation), but for a simple store tool with no output schema, this is a minor omission. Overall adequate.

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

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

Schema has 100% coverage with descriptions for key and value. Description enhances with naming conventions (e.g., 'subject_property') and value examples ('findings, addresses, preferences, notes'), adding practical guidance 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 saves data for reuse across conversations/sessions, with specific examples (resolved ticker, address, preferences). It distinguishes itself from sibling tools recall and forget by explicitly pairing with them.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Provides pairing instructions with recall and forget, guiding agent on complete workflow.

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

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

Discloses that calls cascade through multiple internal endpoints, replacing manual lookups. Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context without contradiction.

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

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

Description is comprehensive yet focused, starting with examples and then detailing supported types. Could be slightly more concise, but structure is logical and every sentence adds value.

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

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

Despite no output schema, description fully explains return values (ticker, CIK, citation for company; RxCUI, ingredient, brand for drug) and mentions internal cascading, making it complete for use.

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

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

Schema coverage is 100%, but description significantly enhances understanding by explaining parameter behavior for each type (e.g., auto-disambiguation, accepted input formats like ticker/CIK/name).

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 uses specific examples ('ticker', 'CIK', 'RxCUI') and clearly states it resolves names to canonical identifiers. It distinguishes supported types (company, drug) with detailed return fields, making the tool's 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?

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' Does not provide explicit when-not-to-use or alternatives, but the purpose is clear and the context of sibling tools implies differentiation.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. Description adds minimal value by specifying 'fastest route' but lacks detail on underlying algorithms or factors like traffic. 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?

Single, clear sentence that immediately conveys the tool's purpose. No unnecessary words.

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

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

With a detailed schema, annotations, and output schema, the description adequately covers the tool's purpose. However, it could mention that it supports multiple waypoints and uses OSRM or similar engine, 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 coverage is 100%, so baseline is 3. Description does not add any parameter-specific information beyond what the schema already provides.

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

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

Description clearly states the tool computes the fastest route between waypoints, specifying verb and resource. However, it does not distinguish from the sibling tool 'trip', which likely provides similar functionality, lowering the score.

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

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

No guidance on when to use this tool versus alternatives like 'trip' or other routing tools. The description only states what it does without context or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value beyond annotations by explaining the underlying tool call (ai_visibility_check), the ranking process, and the specific output fields (score, confidence, signal density). No contradictions with annotations.

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

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

The description is four sentences long, with the purpose stated in the first sentence, followed by the mechanism, use case, and output structure. Efficiently conveys key information without fluff, though slightly longer than needed.

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

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

Given the annotations and full schema coverage, the description provides a complete high-level understanding: it wraps ai_visibility_check, compares multiple entities, ranks them, and returns structured results. It does not mention the 2-8 entity constraint (present in schema) or error handling, but overall is sufficient for understanding tool 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% coverage with detailed descriptions for all 4 parameters. The description does not add new parameter semantics beyond the schema; the schema already includes the note about the first entity being the subject. Baseline is 3 per guidelines.

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 verb ('Compare'), resource ('AI visibility across multiple entities'), and the mechanism (probes each with ai_visibility_check, ranks by score). It differentiates from siblings like ai_visibility_check (single entity) and compare_entities by specifying the competitive audit use case and ranking output.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when NOT to use the tool or mention alternative tools like ai_visibility_check for single-entity checks. It implicitly contrasts with ai_visibility_check but lacks explicit guidance on trade-offs.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds that it fans out to external services, returns a summary block, per-advisory detail, links, alternative versions, and handles graceful degradation with sources_failed. This goes beyond annotations.

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

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

Description is detailed yet concise, front-loading the composite nature and when to use. Every sentence adds value without redundancy.

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

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

No output schema, but description lists all returned fields (summary block, per-advisory detail, links, alternative versions) and explains partial failures. For a complex tool, this is highly 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 has 100% coverage for parameters. Description adds context: scoped packages accepted, version defaults to latest, and mentions that bundlephobia's first measurement can take 5-30 seconds, which is useful behavioral info.

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

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

The description clearly defines the tool as a composite check for npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying 'NPM ecosystem only in v1' and mentioning alternative tools for other ecosystems.

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"'. It also excludes other ecosystems and provides guidance on partial failures and timing issues.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds rich behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K with truncation flag), and that passages include offsets for verification. 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?

Concise with 4 sentences, front-loading purpose and usage, then technical details. No wasted words, 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?

Comprehensive for a tool with 3 parameters and no output schema. Explains return format, algorithm, limitations, and pairing with sibling. All necessary context is covered.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for query and mentions the text cap, but does not significantly enhance parameter understanding beyond what the schema already provides.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the action (search), resource (record), and output (passages with offsets and scores). It distinguishes from siblings like ask_pipeworx_grounded by explicitly pairing with it, indicating a complementary role.

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

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

Provides clear guidance on when to use: 'when the record is too big to cram into the prompt.' It also suggests a workflow with ask_pipeworx_grounded. It does not explicitly exclude scenarios, but the guidance is strong and context-driven.

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

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

Annotations indicate readOnlyHint=false (writes), openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: OAuth requirement, return of subscription id, constraints on delivery (SMS cap, webhook auto-disable after 10 failures, signing secret returned once). 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 long but well-structured, front-loading purpose and requirements. Every sentence adds value (examples, constraints, prerequisites). Could be slightly more concise, but given the complexity (3 params, 5 types, multiple delivery options), the length is justified.

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

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

Covers all necessary context: prerequisites, supported types with parameterization, delivery channels with rules and constraints, return value, and behavioral notes (webhook auto-disable). No output schema, but description compensates adequately. Fully complete for a tool of this complexity.

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

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

Input schema has 100% coverage with descriptions. The description goes far beyond by providing concrete examples (e.g., sec_8k with items:['5.02'], delivery with email/sms/webhook examples) and detailed explanations of type-specific params (e.g., polymarket_edge topic, fred_series series_id).

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 clear verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), specifies the return value ('Returns the new subscription id'), and distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states prerequisites (Pipeworx OAuth account), supported types with examples, delivery channels with constraints (e.g., SMS 10/day cap, webhook auto-disable). However, it does not explicitly state when not to use this tool versus alternatives (e.g., when to use list_subscriptions instead).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the dynamic nature ('drawn from the live catalog') and output structure. 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?

The description is informative but slightly verbose, though it is front-loaded with the purpose and every sentence adds value. It could be slightly more concise.

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

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

Despite no output schema, the description thoroughly explains the return value (category-bucketed examples with tool+argument shape) and usage context. It is complete for an onboarding tool with one parameter.

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

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

Schema coverage is 100% for the single parameter 'topic'. The description enriches it by listing example values (finance, pharma, etc.) and explaining default behavior (full spread).

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: returning categorized example questions and serving as the onboarding entry point. It uses specific verbs like 'returns' and distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicit guidance on when to use ('FIRST when you do not yet know what Pipeworx can do') and how to use the optional topic argument. Implicitly differentiates from meta-tools by positioning it as an introductory tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering core behavioral traits. The description adds no further behavioral details, but does not contradict annotations. 3 is baseline given the annotations' richness.

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. No unnecessary words. It conveys the core purpose efficiently.

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

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

Given the output schema exists and annotations are comprehensive, the description is reasonably complete. It lacks some nuance (e.g., matrix orientation), but the schema likely covers return structure. The tool is simple enough that this is adequate.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description does not add additional meaning beyond what the schema provides (e.g., no explanation of indexing or default behavior). Baseline 3 is appropriate.

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

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

The description clearly states the tool computes a 'distance / duration matrix between source and destination points', which is a specific verb+resource. It distinguishes from sibling tools like 'route' (which likely returns a single route) and 'nearest' (nearest 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?

No explicit guidance on when to use this tool versus alternatives (e.g., 'route' for a single path or 'nearest' for closest point). The description does not specify prerequisites or contexts where it 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?

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds 'TSP-like', implying optimization, but does not elaborate on behavioral traits such as how waypoints are ordered or whether it returns a sequence. With rich annotations, the description provides marginal additional insight, earning a 3.

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, making it concise. However, it omits important details that would help an agent, such as parameter descriptions or usage context. It is not overly verbose, but it sacrifices completeness for brevity, earning a mid-range 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?

Given that an output schema exists and annotations provide safety guarantees, the description could be more complete. It does not explain what 'TSP-like' means in practical terms, what the output represents, or how the inputs affect the solution. For a tool solving an optimization problem, this context is missing.

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

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

Schema description coverage is 60%, leaving parameters like 'profile' and 'coordinates' undocumented. The description does not explain these parameters or clarify their expected format (e.g., coordinates as semicolon-separated pairs). The examples in the schema help, but the description itself adds no value beyond the schema.

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

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

The description clearly states the tool's purpose: solving a TSP-like trip between multiple waypoints. The verb 'solve' and resource 'trip' are specific, and 'TSP-like between multiple waypoints' distinguishes it from simple routing. However, it does not explicitly differentiate from the sibling 'route' tool, which could also handle waypoints.

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

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

No guidance is provided on when to use this tool versus alternatives like 'route' or 'nearest'. There is no mention of prerequisites, when-not to use, or comparison with sibling tools. The description only states what the tool does, not when it 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 adds context beyond annotations: ownership enforcement and deactivation behavior. Annotations already indicated non-destructive, so this adds nuance.

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 action, then constraints. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and relationship to other tools effectively.

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 provides adequate description for the id parameter. The tool description does not add additional parameter details beyond what the schema already offers.

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 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes itself 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?

It explains ownership enforcement and that the row is deactivated not deleted, providing context for when to use. However, it does not explicitly mention alternatives or when not to use.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these by detailing the dual verification pipelines, return values (verdict, actual value with citation, reasoning), and process efficiency (replaces 4-6 sequential calls). No contradictions with annotations.

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

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

The description is well-structured with a clear purpose statement upfront. While somewhat lengthy, every sentence contributes meaningful information. It could be slightly more concise but is still effective.

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

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

With only 2 parameters, full schema coverage, and no output schema, the description compensates well by detailing return values and behavior. It provides a comprehensive understanding of tool functionality without needing an output schema.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by explaining the tolerance_pct override behavior and default logic ('implied by wording, capped at 5'), providing context beyond the schema.

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

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

The description clearly identifies the tool as a claim verification tool with specific trigger phrases and distinguishes two verification paths (SEC EDGAR for company-financial claims, grounded pipeline for others). This effectively differentiates it from sibling tools like 'ask_pipeworx' or 'deep_research'.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides clear context on when to use but does not explicitly state when not to use, though the purpose is well-defined.

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