Pennsylvania DMV (PennDOT)

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds useful behavioral context: default model is free, API key is passed directly to Anthropic (user pays), and returns structured per-model data. No contradiction with annotations.

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

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

The description is front-loaded with core purpose, followed by model details, API key usage, return structure, and use cases. Every sentence adds value, and it is compact without 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's complexity (multiple models, optional API key) and no output schema, the description sufficiently covers return fields (per-model score, confidence, signals, raw_response + combined view). It provides all necessary context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning by clarifying that 'entity' includes brand/product/person/topic, 'models' array accepts specific values, '_apiKey' is only needed with 'anthropic', and 'context' disambiguates common names. 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 probes multiple LLMs for brand/product visibility and scores it 0-100 per model. It specifies the verb 'probe' and resource 'LLMs', and distinguishes from sibling tools like entity_profile or deep_research by focusing on AI visibility measurement.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifies the default model vs. requiring an API key for Anthropic. However, it does not explicitly state when not to use or contrast with specific siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds routing behavior (selects from 5,305 tools, fills arguments) and citation format (pipeworx:// URIs). Does not disclose error handling or rate limits, but with annotations covering safety, a 4 is justified.

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 front-loaded with key directive 'PREFER OVER WEB SEARCH' and includes many examples. While lengthy, every sentence contributes context for agent decision-making. Slightly verbose but justified by complexity.

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

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

Given no output schema, description covers return value (structured answer with stable pipeworx:// citation URIs). Includes extensive usage scenarios and connections to sibling tools. Could mention pagination or limits, but overall adequate for a tool with broad scope.

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

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

Schema description coverage is 100% with each parameter described as alias. Description adds value by explicitly stating that 'question' accepts query, q, prompt, text, input as aliases, clarifying relationship beyond schema. Baseline 3 raised to 4 for added clarity.

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 states specific verb 'routes the question' and resource '5,305 tools across 1,391 verified sources'. Differentiates from siblings like ask_pipeworx_grounded and deep_research with clear use-case boundaries. Includes concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K').

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 mandates 'PREFER OVER WEB SEARCH' for broad categories and provides 'START HERE' directive. Details when to step up to alternative tools (grounded for hallucination-resistant, deep_research for broad/multi-part). Covers both inclusion and exclusion criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint, but description adds valuable context: it is a full working router (not a fallback), experimental nature, candidate lifecycle, and the rationale for comparing results. No contradictions with annotations.

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

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

The description is front-loaded with key purpose and usage, but contains some redundancy (e.g., repeating 'identical universal router'). Could be slightly more concise, but still efficiently communicates necessary information.

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

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

Given the tool's complexity as a beta version of a large router, the description provides sufficient context: identity with stable, experimental nature, current state, and expected behavior. No output schema, but mentions identical response shape, which 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 coverage is 100% with parameter aliases and description for 'question'. The description does not add new parameter-level meaning beyond stating identical arguments to ask_pipeworx, which is already implied. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with identical functionality and experimental routing. It uses specific verb ('ask') and resource ('pipeworx') and distinguishes it from the stable sibling by highlighting the candidate improvements testing.

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

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

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, explains current state (no active candidate matches stable exactly), and notes that results are compared against stable router to decide merges. Provides clear when-to-use guidance.

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

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

Goes beyond annotations (readOnlyHint, idempotentHint) by detailing the extra LLM call cost, the return format including refusal reasons, and the process of extracting only from the tool result. Fully discloses behavioral traits.

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 key information front-loaded. Though slightly long, every sentence adds value. Could be trimmed slightly for conciseness.

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

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

No output schema exists, but the description fully explains the return structure (answer, evidence, confidence, etc.) and refusal reasons. Covers all necessary context for a complex read-only tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description mentions aliases but does not add new meaning beyond the schema. 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 it is a 'hallucination-resistant answer mode' for high-stakes reads, specifying it extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing explicit refusal reasons and evidence return.

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: use when answers will be quoted, cited, or acted on, and the agent must not invent facts (e.g., financial verdicts, medical lookups). Also states to prefer ask_pipeworx for casual lookups, directly addressing 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?

The description goes far beyond annotations, detailing fan-out behavior, response shapes, resolution confidence, parent event extraction, news fallbacks, safety checks, and resolution rule risk. Annotations indicate read-only, idempotent, non-destructive, which the description supports.

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 and well-structured, starting with purpose, then classifiers, examples, response shapes, and edge cases. However, it is quite lengthy and may overwhelm some readers; a slightly more concise version could improve quick scanning.

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 (fan-out, edge cases, resolution rules), the description is remarkably complete. It explains return structure and behavior even without an output schema, covering safety, illiquid markets, and cancellation rules.

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. The description adds context: market can be slug, URL, or text; depth quick vs thorough; include_raw default false with rationale. 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 it researches a Polymarket bet by pulling Pipeworx data. It specifies multiple input formats and distinguishes from sibling tools like ask_pipeworx and polymarket_edges by focusing on market resolution and evidence gathering.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It implies the tool is for research but does not explicitly contrast with alternatives, though the purpose is clear.

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

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

Annotations show readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, read-only operation. The description adds value by detailing data sources (SEC EDGAR/XBRL with off-calendar handling for companies; FAERS for drugs) and sorting behavior. No contradictions.

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

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

The description is concise but comprehensive, front-loaded with familiar trigger phrases. Every sentence adds value: use cases, data sources, sorting, efficiency, and output citations. No fluff or redundancy.

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

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

Given no output schema, the description sufficiently explains return format (paired data + citation URIs) and data fields (revenue, net income, etc.) for companies and drugs. It covers key behavioral aspects and works well with the annotations to provide a complete understanding.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The description goes beyond the schema by providing concrete examples (e.g., tickers/CIKs for companies, drug names) and clarifying behavior like off-calendar fiscal year handling, which enhances semantic understanding.

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 immediately states the tool's purpose with common trigger phrases ('compare X and Y', 'X vs Y') and explicitly defines it as a side-by-side comparison for 2-5 companies or drugs. It clearly distinguishes itself from siblings like 'entity_profile' by advising preference over sequential single-entity lookups.

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

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

The description provides explicit when-to-use guidance: comparisons of entities. It instructs 'ALWAYS PREFER over sequential single-pack lookups', which contrasts with the sibling tool 'entity_profile' for single entities. However, it does not explicitly state when not to use (e.g., for single entity), but the context is clear.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds rich behavior details: account requirements, paid tier, return format (findings packet with evidence/confidence/source/citation/gaps/contradictions), timing estimates (15-90s), second-hop iteration logic, and semantic excerpting. No contradictions with annotations.

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

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

The description is long but front-loaded with critical info (account requirement, alternatives). Every sentence adds value, though it could be better organized with sections. Still earns its keep.

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, no output schema, the description fully covers return format, timing, depth behaviors, and edge cases (gaps, contradictions). An agent has complete context to invoke and interpret results 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%, but the description adds substantial meaning: explains depth enum values in detail (number of facets, hops, contradictions), and clarifies that the question parameter should be broad/multi-part. 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 the tool performs grounded multi-source research across 1391 structured data sources in one call, and distinguishes it from siblings like ask_pipeworx by scope (broad/multi-part vs single lookup) and data type (structured vs news).

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

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

Provides explicit when-to-use guidance: for non-signed-in users, single lookups, or breaking news topics, it directs to ask_pipeworx instead. Also explains depth levels (quick/standard/thorough) and when to prefer each.

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, so the tool is safe and idempotent. The description adds valuable behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output format and usability, going well 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 moderately concise, packing purpose, usage advice, domain list, and output details into a single paragraph. It could be slightly tighter (e.g., the list of domains is long), but every sentence adds value and earns its place. Front-loading the main verb and resource is good.

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 6 parameters (1 required), no output schema, and no nested objects, the description provides enough context: it explains what the tool returns (tool definitions with schemas) and how to use the query parameter. It does not discuss pagination (limit parameter is explained in schema) but the 'top-N' mention is sufficient. An explicit note about ordering or relevance might improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter semantics beyond what the schema provides (e.g., it mentions 'query' is a natural language description, matching the schema). Examples are in the schema examples, not in the description itself. No extra guidance is needed.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses specific verbs ('browse, search, look up, discover') and lists many domains (SEC filings, FDA drugs, etc.), making its resource and action unambiguous. While sibling tools exist, this tool is unique in being a discovery interface, and the description implicitly distinguishes it by advising to use it first.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives clear context but does not explicitly list alternatives or when not to use it beyond the 'not just one answer' hint.

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

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

Discloses behavior beyond annotations: fans out across multiple sources, mentions soft-fail for USPTO due to sunset, describes return fields (cik, filings, fundamentals, patents, news, LEI), and notes it does everything in one parallel call. 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?

Front-loaded with example queries, well-structured. Slightly lengthy but every sentence adds value. Could be trimmed slightly without losing substance.

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

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

For a complex tool with no output schema, the description comprehensively lists all returned data points and special behaviors (e.g., soft-fail). It gives a complete picture of what the agent can expect.

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?

Adds meaning beyond the schema: explains 'value' accepts ticker or CIK, explicitly says names not supported, gives examples. This is valuable context that the schema's descriptions do not fully provide.

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 a 'full cross-source profile of a US public company in ONE parallel call.' It opens with example queries and explicitly distinguishes itself from chaining single-pack lookups, making its purpose unambiguous.

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

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

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

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' is consistent but adds no new behavioral context beyond the obvious.

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

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

Two concise sentences. The action is front-loaded, and every word 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage scenarios, and related tools; 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 has 100% coverage for the single parameter 'key' with a description. The tool description does not add further 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?

Clearly states 'Delete a previously stored memory by key,' providing a specific verb, resource, and method. Distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly lists use cases (stale context, task done, clear sensitive data) and suggests pairing with related tools. Lacks explicit when-not-to-use but positive 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds context about fetching the page, extracting title/description/key links, and emitting standard markdown format. No contradiction, and the description complements the annotation well without over-explaining.

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

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

The description is a single, concise paragraph of about 60 words. It front-loads the primary action and includes essential context without any fluff. Every sentence provides value.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description covers the basic functionality, output format, and use cases. It could briefly mention the default value for max_links in the description itself, but overall it is sufficient.

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 (url and max_links) fully described in the schema. The description does not add additional semantic value beyond what is in the schema, such as clarifying types or defaults. 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 verb 'generate' and the resource. It provides concrete use cases (getting client's site indexed, drafting for own project, auditing competitors) that distinguish it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

Explicitly lists three scenarios in 'Useful for:' section, giving clear guidance on when to use the tool. However, it does not mention when not to use it or provide direct alternatives among siblings, leaving some room for improvement.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields context but does not disclose additional behavioral traits 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?

Two concise sentences, front-loaded with action and return fields, no superfluous 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?

For a simple listing tool with annotations, description adequately explains return fields and usage context. No output schema needed.

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

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

Schema covers 100% of parameters; description does not add meaning beyond parameter descriptions. Baseline 3 applies.

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

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

Description clearly states the action (list) and resource (subscriptions), specifies returned fields, and distinguishes from siblings like subscribe/unsubscribe.

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

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

Provides concrete use cases: review before adding more or find id to cancel. Does not explicitly exclude alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so no contradiction. The description adds context: returns a 'genuine statewide total', substring matching for county, default behavior for year and quarter. It does not discuss rate limits or auth, but with high annotation coverage, the description adds meaningful nuance.

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

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

The description is a single paragraph that front-loads the purpose and then adds detail. It is clear and every sentence adds value, though slightly verbose. Could be tightened but still excellent.

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

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

Given no output schema, the description fully explains what the output contains (counts per fuel type, share, statewide total) and provides example queries. All 4 parameters are documented, and usage guidance is thorough. The description is self-contained and leaves no obvious 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: explains county uses substring match, quarter defaults to latest filed, year defaults to 2026, and limit max 70 with note that PA has 67 counties. The examples also show typical usage.

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

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

The description uses a specific verb ('measure') and resource ('electric-vehicle adoption in Pennsylvania from PennDOT data'). It clearly states what it returns (counts by fuel type per county, share, statewide total) and distinguishes from siblings by explicitly naming pa_dmv_ev_adoption_by_zip and pa_dmv_vehicle_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 provides explicit when-to-use guidance (e.g., 'how many EVs are registered in Pennsylvania', 'EV share in Allegheny County') and clearly states when not to use by directing to sibling tools for ZIP-code detail or full fleet data. It also explains quarter-over-quarter growth via year/quarter arguments.

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

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

Annotations already mark it as read-only and idempotent; the description adds rich behavioral context: data source (PennDOT), types of vehicles counted, total vehicles, plug-in share, scope (1,830 ZIP codes). 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 one focused paragraph, front-loading the purpose and key details. Slightly lengthy but no wasted words; clear and efficient.

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

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

For a 4-parameter tool with no output schema, the description fully explains functionality, parameter behavior, return data, and sibling relationship. Complete enough 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 coverage is 100% with descriptions, baseline 3. The description adds value by explaining how parameters are used (e.g., omit zip to rank, default year, quarter), enhancing beyond schema.

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

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

The description clearly states the tool breaks down EV registrations by ZIP code, gives specific examples (e.g., 'how many EVs in ZIP 19103'), and distinguishes from the sibling tool pa_dmv_ev_adoption for county/statewide data.

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

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

Explicitly tells when to use this tool (ZIP-level queries) vs the sibling for county/statewide, and provides parameter usage guidance: supply 'zip' for one ZIP or omit to rank.

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 no destructive behavior. The description adds context: it returns genuine statewide totals, plug-in counts, and covers entire fleet. 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 somewhat long but front-loaded with key purpose and usage. Every sentence adds value, though minor redundancy could be trimmed. Overall good structure.

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

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

Given 4 parameters, no output schema, and moderate complexity, the description is very complete. It explains return content (counts by county, total, plugin count) and example questions, leaving no major 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% with descriptions for all 4 parameters. The description adds extra context like default values for year and quarter, and examples (e.g., Allegheny county). It complements the schema well.

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

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

The description clearly states the tool counts all vehicles registered in Pennsylvania by county for a given quarter, from PennDOT Driver & Vehicle Services. It specifies it covers all fuel types, returns a statewide total, and distinguishes from the sibling tool pa_dmv_ev_adoption for electric/hybrid breakdown.

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 when to use: for questions about total registered vehicles, county counts, and quarterly trends. It also directs users to pa_dmv_ev_adoption for electric/hybrid breakdown, providing clear alternative guidance.

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

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

Discloses rate limit (5 per identifier per day), free usage, and no quota consumption. Annotations provide minimal behavioral info, so description effectively communicates constraints. 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?

Multiple sentences but each serves a purpose: explaining categories, usage, constraints, and formatting. Concise without unnecessary detail; appropriately front-loaded.

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

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

Given no output schema and moderate complexity (3 params, nested object, enums, rate limit), the description covers all necessary aspects: purpose, usage, parameters, constraints, and behavior. No gaps.

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

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

Schema coverage is 100%, and description adds meaningful guidance: explains enum values (bug, feature, etc.) and advises describing issues in terms of tools/packs. Provides context on message length and specificity.

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 identifies the tool's purpose as sending feedback about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools (research, analysis, utility) by focusing on communication with the team.

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 feedback type (bug, feature, data_gap, praise) and what to avoid (pasting end-user prompts). Also mentions rate limits and quota, providing comprehensive usage context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds valuable context: data is derived from CF analytics-engine, no PII, cached 5min-1h, and self-aggregating signal. This goes beyond annotations.

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

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

Description is two short paragraphs, front-loaded with the main output, and three use cases enumerated efficiently. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: what it returns, how it works, caching, and use cases. 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 has 100% coverage with a single enum parameter and description. Description adds behavioral semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This aids parameter selection.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window (24h, 7d, 30d). The verb 'returns' and resource are specific. It distinguishes from siblings like discover_tools or ask_pipeworx by focusing on trending usage data.

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

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

Explicitly lists three concrete use cases: discovering hot data sources, confirming popular tools, and checking alignment. While it doesn't explicitly state when not to use, the use cases provide clear context for when this tool is appropriate.

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

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

Annotations confirm read-only, non-destructive behavior. Description adds rich behavioral details: partition sum deviation (>3pp triggers signal), Jaccard similarity threshold (0.30), placeholder filtering (>20% placeholder returns null), and fill check against live CLOB depth. 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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with core purpose and mode selection. Every sentence adds value given the tool's complexity. No wasted words.

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

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

Thoroughly covers all aspects for selection and invocation: modes, parameters, internal constraints, response format (opportunities[], fill check results), and references to sibling tool for custom sizing. No output schema is present, but the description explains return fields sufficiently.

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

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

Schema describes both parameters with examples (e.g., 'fed-decision-may-2026'). Description goes far beyond by explaining internal logic: how event slug is used, topic triggers cross-event search, ranking, similarity filter, and placeholder handling. Fully compensates for complexity.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. Describes three distinct modes (no args, event, topic) and 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 advises when to use each mode: 'event (recommended for a specific market)' and 'topic' for cross-event scanning. Explains the no-args default and provides context for when fill check should prevent trading.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value beyond annotations by disclosing caching behavior (1h KV-level), Fed bets exclusion, partition Kelly behavior, and diagnostics availability.

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

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

The description is long but well-structured with clear sections and parenthetical lists. While dense, each sentence adds value for correct invocation 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?

Despite having no output schema, the description thoroughly explains the response structure, including top-level segments, per-opportunity fields, and diagnostics for debugging, making it complete for an agent to understand outputs.

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

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

Schema coverage is 100%, but the description adds significant context beyond schema descriptions, such as the distinction between min_kelly and min_partition_leg_kelly, and practical advice on slippage_pp defaults.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using specific verb 'scan' and resource 'top Polymarket markets'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx-derived edges.

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

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

The description explicitly states the tool is built for 'what should I bet on today' and provides detailed guidance on tradeable-edge knobs and parameter usage. However, it does not explicitly state when not to use this tool or compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that history is bounded by 60-day TTL, snapshots have gaps, and decay uses daily closes. This provides useful context beyond annotations with no contradiction.

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

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

The description is a single paragraph but efficiently front-loads the purpose. It details the output structure, which is necessary since no output schema exists. Some verbosity is justified by the complexity of the response.

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

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

Given no output schema, the description thoroughly explains the response arrays (tracked, expired, snapshot_dates) and their fields, plus limitations. This makes the tool fully understandable without needing to invoke it.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context on defaults (days=14, window='1wk') and clamps (max 30), enhancing understanding beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it's shrinking. This distinguishes it from sibling polymarket_edges which likely provides current edges only.

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 this tool (to assess edge age and trend) and contrasts with a fresh vs old edge scenario. It implies when not to use (for current edges, use polymarket_edges) but does not explicitly exclude 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds rich behavioral context: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and warns about partial fills converting arb into unhedged directional positions. This goes well 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 lengthy but well-structured with headings (SINGLE-MARKET, BASKET) and clear delineation of outputs. Every sentence adds necessary detail for the tool's dual-mode complexity. It is not excessively verbose for the information conveyed.

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 describes return values for both modes, including verdict, per-leg detail, thin_legs, and forced_directional_risk. It covers prerequisites, edge cases (partial fills, thin books), and the risk of unhedged positions. It is complete for the tool's purpose.

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

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

Schema description coverage is 100%, and the description adds significant value: it explains the default for 'side' in basket mode ('auto'), interprets 'size_usd' differently for single-market (spend/target) vs basket (settlement notional), and provides clamping ranges. This enriches the agent's understanding beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly positions itself as a prerequisite tool before using 'polymarket_arbitrage' or 'polymarket_edges', differentiating it from sibling tools.

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

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

The description specifies when to use the tool: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the two modes and the risks of partial fills. It does not explicitly state when not to use, but the context strongly implies it is for risk assessment, not execution.

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

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

The description goes far beyond the annotations by disclosing the compatibility_warning conditions, temporal alignment checks, skipped cross types, and the fact that most pre-mapped topics return compatibility warnings. This adds significant behavioral context that annotations alone do not 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 thorough but lengthy; it could be slightly more concise. However, it is well-structured with clear sections (modes, response, safety fields) and front-loaded with the main purpose, so it earns a high score.

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

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

Given no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) comprehensively. It covers edge cases like compatibility warnings and temporal alignment, making the tool's behavior fully predictable.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains the topic shortcuts list, that explicit tickers override the topic, and provides examples of valid values, making parameter usage clear and actionable.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, differentiating it from siblings like polymarket_arbitrage. It specifies two modes and the response structure, making the purpose unmistakable.

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

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

The description explicitly details the two modes (topic shortcuts and explicit tickers) and warns about compatibility warnings and temporal alignment issues, indicating when the spread may not be meaningful. However, it does not explicitly name alternative tools for when the tool is not appropriate, e.g., single-venue arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context about scoping and the ability to list keys, which goes beyond annotations.

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

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

Three sentences, no filler. Purpose stated first, then usage examples, then scoping and pairing. Every sentence adds value.

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

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

For a simple retrieval tool with one optional parameter and good annotations, the description covers purpose, usage, scoping, pairing, and examples. No gaps.

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

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

Schema coverage is 100% with clear description of the one optional parameter. The description echoes 'omit the key argument' but adds no new semantic information beyond the schema.

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

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

Clear verb 'Retrieve' plus explicit resource: 'value previously saved via remember, or list all saved keys'. Distinguishes itself from sibling tools 'remember' and 'forget' by pairing with them.

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

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

Explicitly states when to use: looking up stored context (ticker, address, research notes). Mentions scoping and pairing with remember/forget. Lacks explicit 'when not to use', but context is 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?

Adds behavioral context beyond annotations by explaining the mark_read effect and payload structure. However, there is an annotation contradiction regarding readOnlyHint and the mutation caused by mark_read.

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

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

Three efficient sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

Covers return fields, filters, mark_read behavior, and alternative access. Lacks pagination or error details but sufficient for a read-heavy tool with strong 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?

With 100% schema coverage, baseline is 3. Description adds meaningful context for parameters like type, since, mark_read, and unread_only, clarifying their use beyond schema descriptions.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on events rather than 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?

Provides guidance on polling ('Polls work fine') and an alternative access method, but does not explicitly state when not to use this tool or compare to siblings.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds valuable behavioral context: it fans out to multiple sources with specific fallback logic (GDELT preferred, GNews when rate-limited), mentions API limitations (USPTO sunset soft-fail), and describes output structure. 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 moderately long but well-organized. It begins with clear usage examples, then explains source behavior, parameter details, and output format. Every sentence contributes useful information, though a minor reduction in verbosity could be justified.

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

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

Given the tool's complexity (multiple data sources, fallback mechanisms, and no output schema), the description covers essential aspects: input formats, source behavior, output structure (changes[], total_changes, citation URIs), and cross-reference to sibling tool. It lacks details on pagination or rate limits but is otherwise comprehensive.

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 significantly enhances parameter meaning: explains 'since' accepts ISO dates or relative shorthand (e.g., '30d'), recommends a default ('30d' or '1m'), and clarifies 'value' can be ticker or CIK. This adds crucial nuance beyond the schema's simple descriptions.

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

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

The description explicitly states the tool provides a change feed for companies, listing example queries and detailing the sources (SEC, GDELT/GNews, USPTO). It distinguishes from the sibling entity_profile by specifying this is for dynamic changes rather than static profiles.

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

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

The description provides explicit guidance: use for 'what's new' queries and recommends entity_profile for static profiles. It also gives parameter examples and explains fallback behavior, helping the agent decide when to invoke this tool.

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

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

Annotations already indicate this is a non-read, non-destructive, idempotent write operation. The description adds useful context: authenticated vs anonymous retention (persistent vs 24-hour), and scoping by identifier. It does not contradict annotations.

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

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

The description is structured with a clear lead sentence, usage guidance, and behavioral notes. It is slightly verbose (e.g., the pairing info could be shorter) but every sentence adds value. It is appropriately front-loaded.

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

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

Given the simplicity (2 params, no output schema, good annotations), the description covers all relevant aspects: purpose, when to use, persistence model, and pairing with siblings. No gaps are evident.

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 both parameters have clear descriptions. The description adds example key formats and value types (findings, addresses, preferences) but these are already inferrable from the schema. The description does not compensate for missing schema info since none is missing.

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

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

The description clearly states the tool saves data for reuse later, with specific examples (ticker, address, preference) and contrasts with sibling tools recall and forget. It uses strong verbs ('Save', 'store', 'reuse later') and clearly identifies the resource (key-value memory).

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 indicates when to use the tool ('when you discover something worth carrying forward') and mentions pairing with recall and forget. However, it does not explicitly state when not to use it or provide alternatives for other memory patterns.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: it states that each call cascades through several lookup endpoints internally, replacing multiple manual lookups. This gives the agent insight into the tool's internal complexity and performance characteristics.

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 separation of supported types. It conveys essential information without unnecessary fluff. However, it is slightly verbose in some parts (e.g., repeating the internal cascading detail) and could be trimmed by a sentence or two while retaining clarity.

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

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

Despite lacking an output schema, the description fully explains the return values for each entity type (ticker, CIK, RxCUI, citation URIs). It also covers auto-disambiguation and internal lookup cascading. For a 2-parameter tool, the description leaves no gaps in understanding what the tool does and what is returned.

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

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

The input schema covers both parameters with 100% coverage. The description adds significant meaning beyond the schema: it explains what each type returns (e.g., company returns ticker + 10-digit CIK + company_name + citation URI; drug returns RxCUI + ingredient + brand + citation), provides example values, and notes auto-disambiguation. This makes parameter usage much clearer.

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

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

The description clearly states the tool's purpose: resolving a name to an official identifier. It provides concrete query examples ('what's the ticker for...') and explicitly distinguishes the tool's role from other tools by saying 'Use FIRST whenever you have a name but need an ID'. The purpose is specific, actionable, and leaves no ambiguity about what the tool does.

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

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

The description gives explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID'. It also details supported entity types (company, drug) with clear input formats (ticker, CIK, name) and explains that using this tool replaces 2-3 manual lookups, providing strong context for when it is appropriate.

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

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

The description explains the probing process ('probes each entity with ai_visibility_check') and the output structure ('ranked list with score, confidence, signal density per entity'), adding value beyond annotations that only declare read-only and idempotent behavior.

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 wasted words. First sentence states purpose, second adds context and return info. Front-loaded and efficient.

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

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

Given no output schema, the description adequately explains return values and process. It could mention error handling or rate limits, but annotations ensure safe read-only behavior.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by clarifying that the first entity is the subject. No additional parameter details beyond schema.

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

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

The description uses specific verbs ('Compare AI visibility across multiple entities side-by-side') and clearly identifies the resource (AI visibility). It distinguishes from the sibling tool 'ai_visibility_check' by focusing on multi-entity comparison and ranking.

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

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

The description provides clear context for use ('competitive AI-marketing audits') and implies when to use (multiple entities). However, it does not explicitly state when not to use or name alternatives like 'compare_entities'.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeout items. No contradiction with annotations.

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

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

The description is well-structured, starting with a clear verb and resource, then detailing return fields, ecosystem scope, and error handling. Each sentence contributes meaningful information; however, it could be slightly more concise by breaking into separate bullet points or paragraphs.

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

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

Despite lacking an output schema, the description fully explains the return block fields, error behavior, and timing. With only two parameters and moderate complexity, the description provides complete contextual coverage, leaving no critical 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% with descriptions for both parameters. The description adds semantic value by clarifying that scoped packages (e.g., '@types/node') are accepted for 'package' and that 'version' defaults to the latest published version when omitted. This goes beyond the schema basics.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering safety, popularity, and size via deps.dev and bundlephobia. It distinguishes itself from sibling tools by focusing on npm package evaluation, with no overlapping tools in the sibling list.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies ecosystem scope ('NPM ecosystem only in v1') and directs other ecosystems to deps.dev:version directly, providing clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), description details embedding model (BGE-base-en), windowing (500-char overlap), 200K char cap with truncation/flagging, and that each passage carries offset for verification.

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 focused paragraph with no wasted words; each sentence adds value. Front-loaded with core purpose, then examples, limitations, and technical details.

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 adequately explains returns (top-N passages with offsets and scores), input constraints (200K chars), and technical behavior (embedding model, windowing). Also provides integration guidance with sibling 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% with good descriptions already. The description adds value by providing concrete examples for text (e.g., SEC 10-K body) and query (e.g., 'supply-chain risk'), and clarifying that text must be 'already pulled'.

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 semantic search inside a fetched record, provides concrete examples (SEC 10-K body, article), and contrasts with the alternative of cramming entire record into prompt.

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 (record too big for prompt) and when not to use (record fits in prompt), and recommends pairing with ask_pipeworx_grounded for grounding. Provides concrete guidance on input content.

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 it is not read-only, not destructive, and idempotent. The description adds significant behavioral context: OAuth requirement, delivery channel limitations (10/day SMS cap, phone verification), always-on feed, and webhook auto-disable after 10 failures. 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 and informative, starting with purpose then requirements, types, and delivery. While it is relatively long, every sentence serves a purpose and it avoids redundancy. Could be slightly more condensed but is still effective.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, prerequisites), the description covers all critical aspects: what it does, what's required, type-specific parameters, delivery options, and limitations. It is fully 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 goes well beyond by providing detailed explanations for each type (e.g., sec_8k with item codes, polymarket_edge with topic examples), delivery options with usage constraints, and specific prerequisites. It greatly enriches the schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by naming specific actions and providing detailed examples of supported subscription types.

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 context including the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It does not explicitly state when not to use or mention alternatives, but the sibling list provides natural separation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. The description adds valuable behavioral context: returns category-bucketed examples with tool+argument shapes, optional topic filter. 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 efficiently structured with alternative phrasings front-loaded, then a clear breakdown of return type and usage. Every sentence adds value, though slightly long. No wasted words.

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

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

For a simple tool with 0 required params and no output schema, the description is complete: it explains exactly what is returned (category-bucketed example questions with tool+argument shapes) and how to use the optional topic. Adequate for an onboarding 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% with one optional parameter. The description adds value by listing example topic values (finance, pharma, etc.) and explaining the effect (focus a category). This goes beyond the schema's brief description.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, with a specific verb 'returns' and resource. It distinguishes from siblings by positioning itself as the 'onboarding entry point' and listing meta-tools like ask_pipeworx as alternatives.

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

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

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

Discloses ownership enforcement, deactivation behavior, and impact on historical events. Complements annotations (readOnlyHint false, destructiveHint false, idempotentHint true) 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?

Three concise sentences, front-loaded with action. No wasted words.

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

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

For a simple tool with 1 parameter and no output schema, description covers ownership, side effects, and link to recent_alerts. Fully sufficient.

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 description for 'id'. Description adds minimal context beyond schema, but baseline 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from related 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?

Provides clear context on ownership enforcement and side effects (deactivation vs deletion), implying when to use. Could explicitly state when not to use (e.g., if hard delete needed), but still 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details the two verification paths (SEC EDGAR XBRL for financial claims, grounded pipeline for others), the verdict types returned, and the evidence format with citations. This adds significant behavioral context.

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

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

The description is well-structured and front-loaded with purpose and triggers. It is somewhat lengthy but each sentence adds value, explaining the tool's behavior and output. Could be slightly more concise, but remains clear and informative.

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

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

Given the lack of an output schema, the description compensates by fully describing the return format (verdict types, actual value with citation, reasoning). It also explains the tool's efficiency (replaces 4–6 sequential calls). This makes the tool's behavior fully understandable for an AI agent.

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

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

Schema coverage is 100%, but the description adds practical context: 'claim' is explained with examples of natural-language factual claims, and 'tolerance_pct' is described as overriding default tolerance with a specific use case (hallucination detection). This goes beyond the schema's descriptions.

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

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

The description explicitly states the tool's purpose: validating natural-language claims against authoritative sources. It provides clear invocation examples ('Is it true that…', 'fact check') and distinguishes between company-financial claims and other types, leaving no ambiguity.

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

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

The description clearly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the different processing paths for financial vs. other claims, providing context for usage, though 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.