US State DMV

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

Annotations already declare read-only and idempotent. Description adds critical details: default free model, optional Anthropic (BYO key with direct costs), and per-model return shape. 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?

Highly concise: first sentence states core action and output, followed by model options, return structure, and use cases. No wasted words; each 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?

Despite no output schema, description describes return shape (per-model fields + combined view). Covers cost, optionality, and default behavior. Complete for the tool's complexity (4 parameters, 1 required).

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 adds value beyond schema: explains default model behavior, cost implications for _apiKey, and disambiguation purpose for context. Clearly helps agent use parameters correctly.

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

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

Clearly states the tool probes LLMs to score AI visibility (0-100) for a given entity. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multi-model scoring and specific use cases (marketing audits, pre-launch checks).

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 use cases and explains default model vs. optional Anthropic integration with API key. Lacks explicit when-not-to-use or comparison to similar tools, but context is sufficient for selection.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds that it returns structured answers with stable citation URIs and routes to verified sources. No contradictions.

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

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

Description is comprehensive but front-loaded with key instruction 'PREFER OVER WEB SEARCH'. Every sentence is valuable, though slightly lengthy.

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

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

Given the complexity (6 params, no output schema, many siblings), the description provides thorough guidance on usage, examples, and alternatives.

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 aliases for question. Description does not add parameter-level details, but the schema already covers all parameters.

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

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

The description clearly states the tool routes questions to one of 5,245 tools across 1369 sources, returning structured answers with citations. It distinguishes 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 to prefer over web search for authoritative data, provides examples, and specifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answer, 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?

The description adds significant context beyond the annotations: it explains the beta nature, that it is a full working router with fallback to nothing, and that no candidate is active. It does not contradict any annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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, consisting of two well-structured sentences. It is front-loaded with the key purpose and efficiently conveys the tool's identity, current status, and usage recommendation without redundancy.

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

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

Given the rich annotations and complete schema, the description is fully adequate. It covers the beta nature, current state, and usage context. No output schema exists but is not necessary for a router tool.

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

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

The input schema has 100% coverage with detailed descriptions and aliases for the question parameter. The description does not add additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router. It specifies the same set of tools and arguments, and distinguishes itself from the stable version by highlighting its experimental edge and candidate routing improvements.

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

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

The description explicitly says to use it when you want the newest routing and that results are compared against the stable router. It notes that no candidate is active currently, so it matches ask_pipeworx exactly, providing clear usage context. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining the refusal mechanism, return format with explicit fields, and the extra LLM call cost. No contradiction with annotations.

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

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

Description is well-structured and front-loaded with essential purpose. While slightly verbose, each sentence adds value (e.g., return format, usage guidance). 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?

Given the tool's complexity (tool selection, extraction), no output schema, and rich annotations, the description covers return format, failure modes, and use context adequately. Sufficient for an agent to invoke correctly.

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

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

All 6 parameters are aliases for 'question', with 100% schema coverage. Description provides additional clarity by listing all aliases, making the parameter purpose unambiguous.

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

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

The description clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads', specifying its mechanism of picking the right tool, fetching data, and extracting answer solely from the tool result. It distinguishes itself from sibling 'ask_pipeworx' by noting the extra LLM call cost and use case.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples. Also advises against use for casual lookups, directing to 'ask_pipeworx' 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 state readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds extensive behavioral context: resolution mechanism, fan-out examples, response shapes, resolver contract, parent event extractor, news fallback, safety for low-confidence matches, closed market handling, wide-spread tradeability, and cancellation rules. 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?

Long but well-structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). Every sentence adds value; no redundancy. Could be slightly more concise but density is justified by tool 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 and high complexity, description is fully adequate. Covers all behavioral aspects, edge cases, and what the agent must inspect. No gaps identified.

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

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

Schema coverage is 100% with all three parameters documented. Description adds significant value: explains market accepts slug/URL/question text, details include_raw size implications, and briefly describes depth options.

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?

Explicitly states it researches Polymarket bets by pulling Pipeworx data. Specifies input types (slug, URL, question text) and output summary. Distinguishes from sibling tools by being comprehensive research, while siblings like 'polymarket_edges' are narrower.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Does not explicitly state when not to use or compare to alternatives, but the implied usage is clear.

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

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

The description discloses behavior far beyond what annotations provide: exact data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific financial metrics, handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This gives agents full transparency.

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

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

The description is front-loaded with example queries, making it easy for agents to recognize matching intents. It is well-structured and each sentence adds value, though it is somewhat lengthy. Still, it earns high marks for clarity and efficiency.

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?

All necessary information for correct invocation is present: purpose, usage guidelines, parameter details, behavioral expectations, and return format. Despite lacking an output schema, the description covers results comprehensively. The tool is complex (two types, multiple entities) but the description is complete.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds valuable context: explains what each type does (company vs drug data), gives examples for values (tickers vs drug names), and reinforces constraints (min 2, max 5). This goes beyond the schema.

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

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

The description clearly states the tool provides side-by-side comparison of 2-5 companies or drugs in a single call. It lists example queries ('compare X and Y', 'X vs Y', 'which is bigger') and distinguishes itself from sequential lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance. It also gives example queries that indicate appropriate contexts. It does not explicitly mention when not to use it, but the implication is clear.

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

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

Disclosures include account requirement, paid tier, parallel decomposition, gap recovery, contradictions scan, time estimates, and hop/citation fields. No contradiction with annotations (readOnlyHint, etc.). Rich beyond structured data.

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

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

Description is lengthy (~300 words) and could be more concise, but it is well-structured with separate concerns. Every sentence adds value, though some repetition exists. Adequate but not optimally trimmed.

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

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

Given 2 parameters, enums, no output schema, and high complexity, description is fully complete: covers prerequisites, alternatives, behavior, limitations, features, and timing. No gaps for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and description adds significant value: explains depth enum behaviors (quick=3, standard=5 with gap recovery, thorough=8 with iterative chase) and that question can be broad. Minor room for improvement but highly informative.

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 multi-source structured research over 1369 data sources in a single call, distinguishing it from siblings like ask_pipeworx (single lookup). Verb+resource is specific and grounded.

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

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

Explicitly explains when to use deep_research vs. ask_pipeworx (single lookup, breaking news), provides account prerequisites, and notes paid plan for 'thorough'. Contextual exclusions are clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. This provides useful behavioral context beyond annotations.

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

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

Three sentences with zero wasted words. Each sentence adds distinct value: purpose, scope, and usage instruction. Front-loaded with the core action.

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

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

No output schema provided, but the description fully explains what is returned (tool names, descriptions, schemas with examples) and that results are directly callable. Complete for a discovery tool with clear annotations.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds value by explaining that query accepts multiple aliases (task, q, description, search) and provides natural language examples. Goes beyond the schema's basic descriptions.

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

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

Explicitly states the verb 'Find tools' and the resource 'by describing the data or task'. Clearly differentiates from sibling tools by listing specific domains (SEC filings, FDA drugs, etc.).

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

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

Provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also details the use case and domains covered.

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, and non-destructive nature. The description adds useful context: results are ranked by the DMV site's own relevance order, and the tool is California-only. 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 two sentences, front-loaded with the core purpose, and includes examples and scope. Every word earns its place; no unnecessary 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?

For a search tool with 2 parameters and no output schema, the description explains what is returned (form name, number, download page) and mentions ranking and geographic scope. It is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%; description reinforces with examples like 'title transfer' and 'REG 227' for query, and mentions limit's default and max. This adds value beyond the schema without repeating all details.

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

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

The description clearly states the tool searches the official California DMV forms catalog, returns form name, number, and download page. It provides example queries like 'title transfer' and distinguishes itself from sibling tools (e.g., dmv_ca_insurance_lookup, dmv_offices) by focusing specifically on forms.

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

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

The description gives clear examples of when to use the tool (e.g., 'which California DMV form transfers a title') and restricts scope to California. However, it does not explicitly state when not to use it or mention alternative tools, though sibling differentiation is implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context: it matches on company name, returns each matching insurer with five-digit NAIC number, and uses California DMV list, which are useful beyond annotations.

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

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

The description is concise at about 50 words, front-loaded with the main purpose, followed by output format and examples. 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?

For a simple lookup tool with one parameter and no output schema, the description covers purpose, input, output format, and source (CA DMV). It doesn't explain error handling or exact output structure, but is largely complete.

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

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

Schema coverage is 100% with a clear description of the 'insurer' parameter. The description reinforces name matching and gives examples, but adds limited new meaning beyond the schema.

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

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

The description clearly states the tool looks up NAIC codes for auto insurance companies from the California DMV list, with specific verb 'look up' and resource. It distinguishes itself from sibling DMV tools by being insurance-specific and provides example queries.

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

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

The description implies when to use (for California insurance NAIC codes) and contrasts with other DMV tools (forms, offices, etc.), but does not explicitly state when not to use or mention alternatives like national NAIC databases.

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 behavior. The description adds valuable context about return data (plug-in counts, fleet share) and state-specific formats, but does not discuss rate limits or authentication beyond mentioning an optional app token.

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

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

The description is thorough but somewhat verbose, mixing state lists and example queries. While every sentence adds value, it could be more structured (e.g., bullet lists) to improve scanability.

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

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

Given the complexity of multi-state data with varying snapshots and no output schema, the description comprehensively explains what data is returned, which states are covered, and how parameters like year and month behave. It leaves little ambiguity for an agent.

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

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

With 100% schema coverage, the baseline is 3. The description adds significant value by providing state-specific groups for the 'group_by' parameter and clarifying defaults for 'year' and 'month', which the schema does not cover fully.

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 retrieves electric-vehicle adoption data from state DMV records, listing the types of questions it answers (e.g., 'how many Teslas are registered in King County') and clearly distinguishing from sibling DMV tools that handle forms, insurance, or general registrations.

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 includes multiple example queries and explains state-specific coverage, providing clear guidance on when to use this tool. However, it does not explicitly mention when not to use it or suggest alternatives, though the sibling context makes this less critical.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds valuable context: Missouri data refreshed daily, Wisconsin 92 service centers with flags for knowledge tests, etc. These go beyond annotations, disclosing coverage scope and update frequency. 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 moderately long but efficiently structured: general purpose, per-state details, example queries. Every sentence adds value. It could be slightly shorter but remains focused and front-loaded with the main action.

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

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

Given no output schema, the description compensates by listing return fields (addresses, hours, phone, coordinates, services) and specifying supported states. It covers the tool's scope well but could mention pagination or default limit (50) which is in schema but not in description.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds minimal new parameter-level info beyond the schema, but it does provide usage context via examples. Baseline score of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description uses a specific verb 'Find' and clearly defines the resource as DMV/BMV/MVA offices with addresses, hours, etc. It lists 10 supported states with per-state details, and gives concrete example queries. This differentiates it well from sibling tools like dmv_ca_forms or dmv_wait_times.

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 example queries that illustrate when to use this tool (e.g., finding offices by city, service type). However, it does not explicitly mention when not to use it or suggest alternatives like dmv_ca_forms for forms. The context is clear but lacks exclusion guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by noting that every response reports grain, as-of date, and whether truncated, and that states publish at different detail levels.

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 somewhat long but front-loaded with core purpose, followed by state details, usage examples, and response notes. Every sentence contributes; could be slightly tighter but overall well-structured.

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

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

Given 13 parameters and no output schema, the description adequately covers sources, grain, as-of date, truncation behavior, and example queries. It could detail return format more, but the description is sufficient for agent usage.

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

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

Input schema covers all 13 parameters with descriptions. The description adds state-specific usage context (e.g., duty only for CA, record_type only for NY) and example queries, which adds meaning beyond the schema.

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

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

The description clearly states the tool returns registered vehicle counts from multiple states, broken down by dimensions like fuel type, make, etc. It distinguishes from sibling tools like dmv_ev_adoption (electric-vehicle counts) and dmv_offices (addresses).

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

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

The description provides explicit usage examples ('how many vehicles in ZIP 90210') and explicitly states when to use alternatives ('For electric-vehicle counts... use dmv_ev_adoption; for office addresses use dmv_offices').

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 explains edge-case behavior: 'Waits read zero and status reads closed outside posted business hours, which is the agency feed reporting an idle queue rather than a missing value.' This adds useful context beyond the annotations (readOnlyHint, openWorldHint). It also states the data is published by the agency, implying authority, but does not cover rate limits or error conditions.

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

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

The description is extremely concise: three substantive sentences plus a clear sibling differentiation sentence. It is front-loaded with the core purpose and contains 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?

Given the tool has no output schema, the description outlines the return fields (average wait, longest wait, queue count, open status). It covers supported states, office types, and the edge case of zero wait. It does not mention pagination or sorting, but the schema's limit parameter hints at pagination. The sibling differentiation is included.

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

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

The schema has 100% coverage with descriptions for each parameter, so the baseline is 3. The description adds overall context about outputs and example queries (e.g., 'how long is the wait at the Raleigh DMV') but does not enhance understanding of each parameter 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 returns live wait times at DMV field offices, specifying the data fields (average wait, longest wait, queue count, open status) and supported states (NC, OR). It distinguishes itself from the sibling tool dmv_offices by noting that dmv_offices is for states without wait feeds.

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 direct guidance on when to use this tool versus dmv_offices: 'Most states publish no wait feed at all — for those, dmv_offices returns addresses, hours and services.' This explicitly directs the agent to the alternative. However, it could be clearer about other contexts where this tool is not 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), mentions patent source sunset (May 2025) and soft-fail behavior, and explains news fallback (GDELT→GNews). 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: it starts with example queries, then gives a high-level purpose, then details the fan-out and return fields. It is slightly lengthy but each sentence adds value. Could be slightly more concise, but overall effective.

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

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

Given the complexity of the tool (cross-source, multiple fields), the description is comprehensive. It lists all returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations and fallback behavior. No output schema exists, but the description sufficiently covers the return structure.

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

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

Schema description coverage is 100% – both parameters have descriptions. The description adds further meaning: for 'type,' it clarifies only 'company' is supported; for 'value,' it specifies ticker or zero-padded CIK, and reaffirms that names are not supported. This goes 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: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific examples like 'Tell me about X' and 'research Acme,' and distinguishes it from chaining single-pack lookups by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name).' Provides clear alternatives.

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

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

Description aligns with annotations (destructiveHint=true) and adds context about clearing sensitive data. Annotations already cover destructive nature, but description provides nuance on why deletion is appropriate.

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

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

Two sentences with no superfluous information. Front-loaded with purpose and immediately followed by usage guidance.

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

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

For a simple delete tool with one parameter, good annotations, and no output schema, the description fully covers purpose, when to use, and pairing with siblings.

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

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

Schema covers 100% of parameters with a clear description. The tool description adds no extra semantic value beyond what the schema provides, meeting baseline expectation for high 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?

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and it distinguishes itself from siblings by name-dropping 'remember' and 'recall' as paired tools.

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

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

Explicitly lists when to use the tool: when context is stale, task is done, or to clear sensitive data. Also implies when not to use by pairing with store/retrieve tools.

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

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

Annotations already declare the tool as read-only, non-destructive, idempotent, and open-world. The description adds behavioral specifics: fetches the page, extracts title/description/key links, and emits standard markdown. This goes beyond annotations by explaining the internal process, though it omits potential limitations like page size or rate limits.

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, well-structured paragraph. The core action is stated in the first sentence, followed by a brief explanation of what the tool does internally, and a clear use-cases list. Every sentence is informative and adds value, with no redundancy.

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

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

The tool has low complexity (2 parameters, no output schema, annotations present). The description explains the output format (single text blob, standard markdown) sufficiently for an agent to understand what to expect. It could mention that the output is plain text, but the current description 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% for both parameters (url and max_links), so the schema already provides full parameter semantics. The description does not add further detail about the parameters, only mentioning them in passing. Baseline score of 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the exact action (fetches, extracts, emits) and the output format. It distinguishes itself from sibling tools by being specifically for llms.txt generation, not general visibility scanning or 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?

The description includes a 'Useful for' section with three concrete scenarios (client indexing, personal project, competitor audit), giving clear context for when to use it. It does not explicitly mention when not to use or list alternative sibling tools, but the use cases are sufficient for typical selection.

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

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

Annotations already declare readOnlyHint and non-destructive nature. Description adds context on returned fields (id, type, params, etc.) and default behavior (active subscriptions), complementing annotations without contradiction.

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

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

Two short sentences; first states purpose and output, second gives usage advice. No extraneous text, front-loaded with essential information.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description adequately covers purpose, output fields, and usage context. No gaps detected.

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 only parameter. Description does not add extra meaning beyond the schema, meeting baseline expectation.

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

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

The description clearly states 'List the caller's active subscriptions' with specific fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use and excluding other contexts.

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

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

The description adds behavioral context beyond annotations: rate limits (5 per identifier per day), free usage, and how feedback affects roadmap. No contradictions with annotations.

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

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

The description is three sentences, front-loading purpose, then usage, then behavioral details. Every sentence adds value with no redundancy.

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

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

The description covers purpose, usage, behavioral constraints, and schema details comprehensively. No output schema needed; the tool is well-documented for its complexity.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning by explaining enum values, context structure, and message constraints (specific, 2000 chars max).

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, or praise. It uses specific verbs and distinguishes from siblings by focusing on tool feedback.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and what not to do (don't paste user prompt). It provides clear context without explicitly naming alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, signaling a safe read operation. The description adds valuable context: it is 'self-aggregating signal derived from CF analytics-engine, no PII', and specifies caching duration (5min-1h). This goes beyond annotations to inform the agent about data freshness and privacy.

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 focused sentences plus a bulleted list of use cases. Every sentence adds distinct value: what it returns, why it's useful, and how it works. It is front-loaded with the core purpose and well-structured without redundancy.

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

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

Given only one optional parameter with 100% schema coverage, the description is complete. It explains the return structure (top tools, packs, volume), provides usage guidance, and appears sufficient for correct invocation. The output is implied, so lack of output schema is not a gap.

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

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

The schema covers the single parameter 'window' with an enum and description. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the appropriate value based on intent, enhancing the schema's technical specification.

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 returns 'top tools, top packs, and total call volume' based on recent agent activity. It uses a specific verb ('returns') and clearly defines the resource. It uniquely describes the tool's purpose among siblings, distinguishing it as a trend/analytics tool rather than a query or action 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 lists three concrete use cases (discovering hot data sources, confirming canonical choices, seeing alignment with agent needs) and explains window semantics. It does not explicitly state when not to use it, but the use cases provide strong guidance. Caching behavior is also mentioned, helping manage expectations.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds scanning scope, filtering logic (partition filter, semantic anchor), fill check details, and when not to trade. No contradiction with annotations.

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

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

Description is well-structured with sections (modes, semantic anchor, partition filter, response, fill check) but quite long. Every sentence adds value; could be slightly trimmed but no wasted text.

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

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

Despite no output schema, description details the return structure (opportunities[], partition_check, fill_check) and important conditions. Sufficient for an agent to understand outcomes.

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

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

Schema already describes both parameters with 100% coverage. Description adds useful context like mention of event slug format and topic as seed question, enhancing usability but not essential.

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

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

Description starts with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' – a specific verb+resource+method. Differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: no args for trending_scan, event for specific market, topic for cross-event. Also provides recommendation ('event (recommended for a specific market)') and explains what each does.

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=false, but the description adds valuable behavioral context: caching ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics, and detailed edge calculation logic. No contradictions with annotations.

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

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

The description is well-structured with clear sections (model families, response segments, knobs, caching) and front-loads the core purpose. However, it is verbose with detailed coefficients and technical specifics that could be streamlined. It earns its length but could be 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?

Given the complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the response structure, edge computation, filtering, caching, and why segments might be empty. It leaves very little ambiguity for an agent to understand and invoke the 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, but the description adds substantial meaning beyond the schema. For example, for 'slippage_pp' it explains Polymarket's zero fees and typical bid/ask costs, and for 'min_partition_leg_kelly' it clarifies why min_kelly does not apply to partition arbs. Every parameter has enriched guidance that helps the agent use them correctly.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement. The specific verb 'scan' and resource 'Polymarket markets' with a defined scope make purpose very clear.

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

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

The description provides a clear usage scenario ('what should I bet on today') and explains that agents discover opportunities without paging hundreds of markets. It also details tradeable-edge knobs and filtering. However, it does not explicitly state when not to use this tool versus siblings like polymarket_edge_tracker or polymarket_fill_risk, leaving some ambiguity.

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

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

Annotations are readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: the exact output structure (tracked[], expired[], snapshot_dates[]), the meaning of sign in edge_pp_net, and that decay is from daily closes, not intraday. 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 purpose, then details output in a structured format. It is fairly concise given the complexity, though some sentences could be tightened. It earns its length.

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

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

With no output schema, the description fully explains the return fields and edge cases (gaps, sign meaning, limits). It covers all necessary aspects for an agent to use the tool correctly. Very complete.

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

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

Schema coverage is 100% with both parameters described. The description clarifies the clamping behavior for 'days' (2-30) and the default for 'window', but this adds little beyond the schema. Baseline is 3, and no additional parameter semantics are provided.

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: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers the question 'how long has this edge existed and is it shrinking?'. Among siblings like 'polymarket_edges' and 'polymarket_arbitrage', this tool is distinguished by its focus on time-series analysis.

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

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

The description explains when to use the tool (to distinguish fresh edges from aged ones) and includes context that an old wide edge is different. It also mentions limits like the 60-day snapshot TTL. However, it does not explicitly compare to siblings or state when not to use it.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which align perfectly with the description's characterization as a risk check. The description adds behavioral details such as walking the ladder, returning a verdict (clean|degraded|cannot_fill), and explaining forced directional risk, exceeding 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 comprehensive but somewhat lengthy; it uses line breaks effectively to separate modes and returns. Every sentence adds value, but it could be slightly more concise by breaking into bullet points. Nonetheless, it is well-structured and front-loaded with the core purpose.

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

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

With no output schema, the description compensates by enumerating all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers both modes and the critical risk of unbounded directional exposure. The definition is fully complete for an AI agent to use correctly.

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

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

Schema description coverage is 100%, yet the description adds significant meaning: it clarifies that market and event are mutually required modes, explains side default for basket (auto from partition sum), and specifies how size_usd is interpreted for basket (settlement notional S, shares per leg paying $1). This goes beyond the schema descriptions.

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

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

The description explicitly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and distinguishes between single-market and basket modes. It clearly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about partial basket fills converting an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use context.

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

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

Goes far beyond annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), explaining when spreads are meaningful vs not, and describing the matching algorithm. Annotations already mark read-only, idempotent, and non-destructive; description adds critical operational context.

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

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

Well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS). Front-loaded with key purpose. Slightly verbose in safety field explanation, but necessary for clarity. Could be tightened without losing meaning.

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

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

Comprehensive coverage for a complex tool with no output schema. Describes response structure (leg-by-leg prices, top_spreads_pp), safety fields, and edge cases. All necessary information for an agent to understand behavior and interpret results is included.

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?

Parameters are well-described in the schema (100% coverage). The description adds interaction semantics (topic overrides, explicit parameters override topic mapping) and provides examples. Adds value beyond schema without redundancy.

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 computing cross-venue spread between Kalshi and Polymarket for the same question. Mentions specific resources (venues, events, modes) and distinguishes from sibling tools like polymarket_arbitrage by emphasizing multi-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?

Explicitly states two usage modes (topic shortcuts and explicit tickers) with examples. Includes when to use each mode and warns about compatibility issues (compatibility_warning). Could be improved by explicitly mentioning when not to use, but provides strong contextual cues.

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, idempotent, non-destructive. The description adds behavioral details: scoping (anonymous IP, BYO key hash, account ID) and listing behavior when key omitted. No contradiction.

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

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

Three sentences, front-loaded with action, then usage, then scope. No wasted 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?

Given one optional parameter, thorough annotations, and no output schema, the description covers purpose, usage, behavior, parameter, and scope completely. Nothing 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 coverage is 100% (key parameter fully described). Description adds functional context (omit to list all keys, pairing with remember/forget) and scoping details, which adds value beyond the schema.

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

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

The description uses a specific verb 'retrieve' and resource 'value previously saved via remember', and clearly 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?

The description explicitly states when to use (look up previously stored context) and names alternatives: 'Pair with remember to save, forget to delete.' It also explains scoping and the option to list all keys.

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

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

The description states that setting mark_read:true flags events as read, modifying server state. This contradicts the annotation readOnlyHint=true, which indicates no side effects. Per scoring guidelines, contradiction results in score 1.

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 with no wasted words. It front-loads the primary action and efficiently covers return fields, filtering, side effect, and alternative endpoint.

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 is a simple read operation with no output schema, the description covers all necessary aspects: what it returns, parameters, usage patterns, and an alternative access method. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example for type ('sec_8k'), clarifying the ISO timestamp for since, and explaining that mark_read:true flags events read for subsequent calls.

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

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

The description clearly states the tool pulls fired events from subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools by being specific to alerts and providing an alternative HTTP endpoint.

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 explains when to use filters (type, since) and the mark_read flag to control read state. It also mentions polling is fine and gives an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: fan-out to multiple sources, fallback logic, soft-fail for patents API, and return format (changes[] grouped by source, total_changes, pipeworx:// URIs).

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, front-loading purpose with example queries, then detailing sources, parameters, return format, and alternative. Every sentence adds value, though it could be slightly more concise by separating examples from technical explanation.

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

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

Given the tool's complexity (multi-source, fallback, soft-fail, no output schema), the description is very complete. It covers all sources, accepted date formats, fallback behavior, return structure, limitations, and a sibling alternative.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: examples for `since` (ISO date or relative, recommended '30d'), explanation of `value` (ticker or CIK), and that `type` only supports 'company'.

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: providing a change feed for a company over a time window, with example queries like 'What's new with X'. It distinguishes from the sibling tool 'entity_profile' by explicitly saying when to use that instead.

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

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

The description gives explicit when-to-use guidance with natural language examples and specifies when to use the alternative 'entity_profile'. It also explains fallback behavior (GDELT preferred, GNews when rate-limited) and soft-failure for patents.

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

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

Adds significant behavioral context beyond annotations: key-value paired by identifier, authenticated persistence vs 24-hour retention for anonymous, and pairing with recall/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?

Four sentences, front-loaded with purpose, each sentence adds value. Could be slightly more concise but well-organized.

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?

Completes the picture: explains storage mechanism, scope, persistence, and usage with sibling tools. No output schema, but description covers necessary context.

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

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

Schema covers both parameters fully (100% coverage). Description does not add extra parameter-specific details beyond the schema, staying at baseline.

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

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

The description uses a specific verb 'Save' and resource 'data the agent will need to reuse later', and distinguishes itself from siblings by naming recall and forget as companion 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?

Clearly states when to use: 'when you discover something worth carrying forward', with concrete examples. Mentions alternatives recall and forget, but lacks explicit 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable context: 'Each call cascades through several lookup endpoints internally' and 'auto-disambiguated' for company. This reveals internal behavior that helps the agent understand performance and logic, without contradicting any annotations.

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

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

The description is concise yet thorough, front-loaded with example queries that immediately convey purpose. Every sentence provides unique value, with no redundancy or unnecessary details. It efficiently covers usage, supported types, and return values.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is complete. It specifies return values for each type (including citation URIs), mentions auto-disambiguation for company, and explains internal cascading behavior. No additional information is needed for an agent to effectively 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?

The schema covers 100% of parameters with descriptions, but the tool description enhances understanding with concrete examples (e.g., 'ticker (AAPL)', 'CIK (0000320193)') and explains what each type returns. This adds meaning beyond the schema's enum and type definitions, justifying a score above baseline 3.

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

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

The description clearly defines the tool's purpose: resolving a user-spoken name to a canonical identifier. It uses specific verbs like 'resolve a user-spoken NAME to the canonical/official identifier' and provides concrete example queries ('What's the ticker for…'), making the action and resource unambiguous. The tool is well distinguished from siblings like 'ask_pipeworx' which handle general Q&A, whereas this tool is specifically for entity resolution.

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

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

The description explicitly instructs to 'Use FIRST whenever you have a name but need an ID', setting clear usage context. It also lists supported entity types (company, drug) and explains what inputs each accepts, effectively guiding when to use. However, it does not explicitly mention when NOT to use or name alternative tools for already-known IDs, slightly reducing guidance completeness.

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

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

Annotations already convey readOnly, idempotent, and non-destructive nature. The description adds valuable detail about internal calls to ai_visibility_check and the output structure (score, confidence, signal density), which is beyond the annotations.

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

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

The description is two well-structured sentences with no wasted words; it is front-loaded with the primary purpose and immediately useful.

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 moderate complexity (4 params, no output schema), the description covers the return format and usage context adequately. It lacks details on error handling or ranking algorithm but is sufficient for agent decision-making.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds extra semantics by specifying that the first entity is treated as the 'subject' and the rest as competitors, which is not in the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, explicitly distinguishes from the single-entity sibling 'ai_visibility_check', and uses specific verbs like 'scan' and 'compare'.

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 provides clear usage context for competitive AI-marketing audits and implies the alternative 'ai_visibility_check' for single entities, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds valuable context: partial failures, bundlephobia first measurement delay (5-30s), and that sources_failed will list failures while other data still returns. 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 moderately long but each sentence adds value. It front-loads the core purpose and then provides details on behavior, limitations, and output. Could be slightly more concise, but structure is logical.

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 return format: summary block with 10 fields, per-advisory detail, links, alternative versions, and sources_failed. Covers all aspects of the tool's complex behavior.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds little beyond schema (mentions scoped packages and default version), but it provides overall context that helps an agent understand the meaning of parameters in the tool's behavior.

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

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

The description clearly states it performs a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by focusing on npm package evaluation, and uses specific verb 'scan' and resource 'dependency'.

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 tells when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM ecosystem only in v1, and mentions fallback for other ecosystems via deps.dev:version.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flagging. These go beyond annotations, but could mention rate limits or idempotency explicitly.

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 with a clear purpose. Front-loaded with the core action, then usage, then pairing, then technical details. No unnecessary words. Perfectly 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?

Given no output schema, description explains return format: 'top-N passages with character offsets and similarity scores'. Also mentions offset for verification. Covers all necessary aspects for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: 'text' is a 'fetched record', 'query' is 'natural-language query' with examples, 'limit' default is 5. It also explains the character limit in text. This exceeds baseline.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, long tool result). It distinguishes itself from siblings like ask_pipeworx_grounded by explaining the pairing pattern. The verb 'search within' matches the name and title.

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

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

The description says 'Use when the record is too big to cram into the prompt' and explicitly pairs with 'ask_pipeworx_grounded'. While it doesn't list explicit when-not-to-use scenarios, the context is clear. It could improve by mentioning alternatives for smaller records, but the guidance is strong.

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 non-readOnly, idempotent, non-destructive. The description adds substantial behavioral context: subscription creation returns an id, webhook signing secret is returned once, delivery channels have specific behaviors (always-on feed, optional email/SMS/webhook with constraints). 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 well-structured: first sentence states purpose, then prerequisites, then types with examples, then delivery channels. It is somewhat lengthy but all information is relevant and earnestly placed.

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 covers return value (subscription id), prerequisites, type-specific parameter examples, delivery channel details, and constraints (SMS cap, webhook auto-disable). It is sufficiently complete for an AI agent to correctly invoke the 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 the description enriches parameter understanding with concrete examples for each type (e.g., items:["5.02"] for sec_8k) and additional constraints for delivery fields (phone verification, SMS cap). This adds significant value beyond the schema.

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

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

The description clearly states that the tool creates a proactive monitoring subscription, lists supported event types (sec_8k, polymarket_edge, fred_series, etc.) and delivery channels. It distinguishes itself from sibling tools 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?

The description specifies a prerequisite (Pipeworx OAuth account) and details delivery channel constraints (SMS must be verified, 10/day cap; webhook auto-disabled after 10 failures). While it does not explicitly state when not to use, the context and examples provide clear guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that it returns structured example questions with tool+argument shapes drawn from a live catalog, and that calling with no arguments gives a full spread. This adds behavioral context beyond annotations.

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

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

The description is detailed yet efficient, front-loading alternative phrasings and clearly conveying purpose, scope, and usage. Every sentence adds value, though it is slightly dense and could be broken into shorter sentences for readability.

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

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

Given one optional parameter and no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and when to use it. No gaps remain for an agent to understand invocation and outcome.

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 only parameter 'topic', with description listing valid values. The tool description supplements this by explaining the effect of omitting the parameter (full spread) and giving example topic values, adding meaningful usage context.

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

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

The description clearly states the tool returns example questions categorized by topic, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx or domain-specific tools by explicitly stating its role: 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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 when-to-use guidance (first tool for onboarding) and when to pass topic vs. omit. While it doesn't explicitly list alternatives, the context and phrasing make usage unambiguous. Missing explicit 'when not to use' but sufficient.

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

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

Annotations indicate non-read-only, non-destructive, and idempotent. The description adds that the row is 'deactivated (not deleted)' and 'historical events stay available', which clarifies the behavior beyond annotations. 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 consists of two concise sentences that front-load the main action and provide necessary details without extraneous information.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description adequately covers purpose, ownership constraints, and the deactivation behavior. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a clear description for the single parameter 'id'. The tool description does not add additional semantic detail beyond referencing 'by id', so baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' using a specific verb and resource, and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description includes ownership enforcement ('you can only cancel your own subscriptions'), providing a clear condition for use. It does not explicitly exclude scenarios, but offers sufficient context.

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

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

Annotations provide read-only, open-world, idempotent, and non-destructive hints. The description adds behavioral context: it returns a verdict with a pipeworx:// citation and reasoning, explains the two processing paths (SEC EDGAR vs grounded pipeline), and mentions tolerance override. No contradictions, but could disclose more about dependencies or limitations.

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

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

The description is well-structured with front-loaded examples and clear sections. While slightly lengthy, every sentence adds value and avoids redundancy. Minor repetition exists, but overall it is efficient given the tool's complexity.

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

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

Given the two parameters (both well-described), high schema coverage, and rich annotations, the description thoroughly explains the output format (verdict, value, citation, reasoning) and both processing paths. It covers all essential aspects for a claim verification tool, leaving no significant gaps.

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

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

Schema coverage is 100%, and the description adds value beyond schema descriptions by providing examples for the 'claim' parameter (e.g., 'Apple's FY2024 revenue was $400 billion') and explaining the 'tolerance_pct' range and override behavior.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, with specific examples like 'Is it true that…' and 'fact check'. It distinguishes the tool from siblings by mentioning it replaces 4-6 sequential calls and separates financial claims from other factual claims.

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

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

The description explicitly says to use this tool 'whenever the agent needs to check whether something a user said is factually correct' and explains the automatic routing for different claim types. However, it does not explicitly state when NOT to use it or compare with specific siblings in the provided list, missing some guidance on alternatives.

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