Arcgis Tucson

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the probing mechanism, scoring (0-100), per-model response structure, and the requirement for a BYO key for Anthropic. No contradictions with annotations.

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

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

Three sentences with essential information front-loaded: main action, default model, parameter guidance, and return structure. No filler; every sentence serves a purpose.

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

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

For a tool with 4 parameters, no output schema, and no nested objects, the description adequately covers behavior, parameter usage, and output format (per-model fields + combined view). It is complete enough for an agent to use 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%, so baseline is 3. The description adds meaning by explaining the `_apiKey` purpose (BYO for Anthropic) and how `context` disambiguates common names. 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 uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs for what they know about a business/brand/product/topic'). It distinguishes from siblings by focusing on AI visibility scoring, a unique function among the listed tools.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides guidance on when to pass `_apiKey` for Anthropic. While it doesn't explicitly exclude scenarios, the instructions are clear and contextually appropriate.

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

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

Annotations already convey readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only profile. The description adds behavioral context beyond those annotations: it routes to thousands of sources, fills arguments, returns structured answers with citations, works on every tier, and is a single fast call. It does not disclose failure modes or clarification behavior, but the added context is valuable and does not contradict 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, front-loading the critical directive ('PREFER OVER WEB SEARCH') before elaborating on capabilities, use cases, examples, and alternatives. While some sentences could be trimmed, the detail is justified for a tool with broad routing capabilities, and the organization makes it easy to scan.

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

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

For a complex router tool with no output schema, the description covers the tool's purpose, usage context, examples, and alternatives thoroughly. It does not mention error handling or rate limits, but the guidance provided is sufficient for an agent to decide when and how to invoke the tool. The examples and explicit positioning relative to siblings make it contextually complete.

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

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

The input schema has 100% coverage: all parameters are documented, with the primary 'question' parameter described as 'Your question or request in natural language' and five aliases explicitly listed. The description's examples reinforce question quality but do not add parameter-level meaning beyond the schema. Given the high schema coverage, the 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 states a specific action: it routes questions to one of 5,501 tools across 1,441 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It clearly distinguishes this tool from siblings by positioning it as the default entry point and explicitly 'prefer over web search'. The verb+resource combination is unambiguous and highly specific.

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

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

The description gives explicit when-to-use guidance: 'START HERE for most questions' and 'PREFER OVER WEB SEARCH'. It also names alternatives and when to step up: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions. Example queries further illustrate appropriate usage, making the guidance actionable and 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 the annotations (readOnly, openWorld, idempotent), the description discloses critical experimental behavior: candidate routing improvements may be enabled live, the tool is a full working router with no fallback, and its results feed into comparison for merges. This adds valuable context about volatility and the tool's role in evaluating routing changes, which annotations cannot convey.

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

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

The description is moderately long but efficiently conveys needed caveats: beta nature, current equivalence, experimental candidate handling, and comparison workflow. Every sentence adds useful information, though it is slightly verbose compared to a leaner alternative like 'Beta of ask_pipeworx with live routing experiments.'

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 (5501 tools) and lack of output schema, the description explains that the response shape is identical to ask_pipeworx, which is sufficient as a reference point. It also covers the beta context and comparison mechanism. Missing explicit return-value details, but the stable sibling reference fills the gap. Overall complete for a routing 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 each parameter described as an alias for 'question', so the schema already defines all six parameters. The description adds no additional parameter-level meaning or examples, leaving the tool's core input understood from the schema alone. Baseline 3 is appropriate since the description does not compensate 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 this is a beta version of ask_pipeworx, an 'identical universal router' with the same tools and response shape. It immediately distinguishes itself from the stable sibling ask_pipeworx by framing itself as the experimental variant with candidate routing improvements. The purpose is specific and cannot be confused with other tools.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide what merges, and notes that currently it matches ask_pipeworx exactly since no candidate is active. This fully informs when to choose this tool over the stable alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds crucial context about refusal behavior (specific refusal_reason values), the extra LLM call cost, and the guarantee of not inventing facts. This goes well beyond annotations without contradicting them.

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

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

The description is dense but every sentence conveys essential information: purpose, routing, extraction guarantee, return shape, refusal reasons, usage examples, and cost trade-off. It is front-loaded with the primary purpose and efficiently structured.

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

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

Despite lacking an output schema, the description effectively documents the return format and all possible refusal reasons, compensating fully. Combined with rich annotations and sibling context, the description gives the agent everything needed 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% — all six parameters are documented as aliases for the same question string, with a clear description. The description does not add parameter-specific details, which is acceptable since the schema carries the heavy lifting. 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 opens with a specific phrase 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers using ONLY the tool result content. It explicitly contrasts with sibling ask_pipeworx by noting the same routing but a grounded extraction step, making the tool's unique role clear.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' including a cost trade-off. This directly addresses when to use this tool vs. the sibling.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, wide spread markets, resolution-rule risk. 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?

Long but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Each sentence adds value but could be slightly more concise.

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

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

Given complexity, no output schema, and 3 params, the description covers all necessary context: resolution types, edge cases, blocking paths, and detailed behavioral nuances.

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 3 params (market, depth, include_raw). Description adds meaning: depth 'quick vs thorough', include_raw default false with recommendation, and market input format examples.

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

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

States clearly that it researches Polymarket bets by pulling Pipeworx data. Specific verb+resource and distinguishes from siblings.

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

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

Explicitly states when to use with examples like 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. No explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral details: pulls latest 10-K for companies, handles off-calendar fiscal years, returns sorted results, and includes citation URIs. No contradictions.

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

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

Description is fairly long but informative. It starts with user-facing example queries, then explains behavior and data sources. Every sentence adds value, though some redundancy exists (e.g., repeating entity count limits already in schema). Well-structured and 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 complexity of comparing entities and the lack of output schema, description provides complete context: data sources (SEC EDGAR, FAERS), handling of fiscal year differences, sorting behavior, and return format (paired data + citation URIs). Annotations cover safety concerns, so no gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema: explains that 'company' type pulls revenue/net income/cash/debt from SEC EDGAR/XBRL, and 'drug' type pulls FAERS adverse-event counts. It also clarifies that values should be tickers/CIKs for companies and drug names for drugs, with min/max constraints repeated.

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

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

Description explicitly states side-by-side comparison of 2-5 companies or drugs, with example queries like 'X vs Y' and 'rank these companies'. It clearly distinguishes from sibling tools by stating 'ALWAYS PREFER over sequential single-pack lookups'. Verb+resource is specific.

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

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

Description explicitly says when to use (comparing entities head-to-head) and when not to (avoid sequential lookups). It provides concrete examples of queries and explains behavior for 'largest'/'most' queries, guiding the agent on input phrasing.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses many behavioral traits: account/auth requirements, paid plans, latency expectations (15-60s, ~90s for thorough), output packet structure (evidence, confidence, source, gaps[], contradictions[]), semantic excerpting, and citation policy. It significantly enriches the agent's understanding of what happens when invoked.

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 densely informative, front-loading critical auth/alternative info and then logically organizing behavior, limitations, and performance expectations. While it is verbose, most sentences earn their place; minor redundancy exists (e.g., repeating 'thorough is paid' in both description and schema), but it does not detract significantly.

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 (parallel facets, hops, contradictions) and the absence of an output schema, the description fully covers what the agent needs: inputs, outputs (findings packet fields), failure modes (gaps[]), limitations (not open-web), and performance. No critical aspect is left unexplained.

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 schema itself thoroughly describes both parameters (question and depth) with enum meanings and defaults. The description adds little beyond the schema—only minor clarifications like 'broad/multi-part is fine' and the paid-plan note for thorough, which the schema already contains. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, distinguishing it from open-web search and sibling tools like ask_pipeworx. It specifies the verb ('research'), resource ('1441 STRUCTURED data sources'), and the unique decomposition/parallel-routing behavior, leaving no ambiguity about its purpose.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: recommends it for broad/multi-part structured-data questions, directs single lookups and breaking-news topics to ask_pipeworx, and even notes account-tier prerequisites. This is textbook usage guidance with named alternatives and exclusions.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N most relevant tools with full schemas and examples, ready to call, no second lookup needed.

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

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

Four sentences front-loaded with purpose, followed by domain list and output behavior. Every sentence adds value with no waste.

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

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

Given 6 parameters, no output schema, and sibling tools list, the description explains what the tool does, when to use, and what it returns. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with full descriptions of each parameter including aliases. Description mentions aliases for query but adds no new semantics beyond the schema.

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

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

Description clearly states the verb 'Find tools' and resource 'by describing the data or task', listing many domains. It distinguishes from sibling tools which are for specific tasks like bet_research or deep_research.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set'. Implies not for single answers but no explicit when-not 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 declare readOnlyHint=true, idempotentHint=true. The description adds concrete behavioral details: fans out across multiple APIs, returns specific fields (cik, filings, fundamentals, patents with sunset caveat, news, LEI), and notes soft-fail for patents. 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 examples first, then explanation of data sources and return fields. Slightly verbose but every sentence adds value. Could be trimmed slightly but remains efficient for the complexity.

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

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

Despite no output schema, the description comprehensively lists return fields and sources, including limitations (US public companies only, patent API sunset, name restriction). Provides full context for an agent to decide if this tool meets the user's need.

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

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

Schema has 100% coverage with descriptions for both parameters. The description further clarifies: type enum only 'company', value accepts ticker or zero-padded CIK, and explicitly states names are not supported, referencing resolve_entity. Adds meaningful context beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with example queries like 'Tell me about X' and names specific data sources (SEC, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings like resolve_entity and compare_entities by focusing on holistic, multi-source retrieval.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack...' for holistic queries and advises using resolve_entity first if only a company name is available. This provides clear when-to-use and when-not-to-use guidance, directly addressing the sibling tools.

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

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

Annotations already indicate destructiveHint=true, so description's 'Delete' is consistent. Adds value by specifying 'clear sensitive data,' 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?

Two concise sentences with no wasted words. Front-loaded with the core action and usage guidance.

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

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

Single parameter, no output schema, strong annotations. Description provides all needed context: what it does, when to use, and relation to sibling tools.

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

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

Schema coverage is 100% for the single parameter 'key' with description 'Memory key to delete'—same as schema. No additional meaning added beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource. Distinguishes from siblings by mentioning 'Pair with 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 gives usage contexts: 'when context is stale, the task is done, or you want to clear sensitive data' and mentions pairing with related tools.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds detail: fetches page, extracts title/description/key links, emits standard format. It explains the operation flow, complementing annotations well.

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 fairly concise with three logical segments: purpose, process, use cases. No redundant information, though could be slightly tighter. Front-loaded with key action.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, how the output looks, and why it's useful. No missing context for selection or invocation.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. The description does not add extra parameter details beyond the schema, but the schema already provides adequate descriptions for 'url' and 'max_links'.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with specific verb and resource. It uniquely distinguishes itself among sibling tools (e.g., compare_entities, deep_research) by focusing on AI crawler indexing.

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

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

The description lists three concrete use cases (client indexing, own project drafting, competitor auditing). It does not explicitly state when not to use or suggest alternatives, but the use cases provide clear guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, repeatable operation. Description adds valuable context about what exactly is returned (fields, geometry type, etc.), which is not covered by annotations. 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?

Single sentence that is front-loaded with the main action and resource, then lists all returned elements. Every word is necessary; no fluff. Highly 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?

With no output schema, the description adequately lists the main returned components (fields, geometry type, record count, capabilities). Could mention error handling or format structure, but for a simple schema tool this is sufficient. Context signals (e.g., 1 param, no output schema) are properly addressed.

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

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

Input schema has one parameter 'url' with a brief description. The description adds a real-world example and context ('by url'), enhancing meaning beyond the schema. Schema coverage is 100%, so baseline is 3; additional context justifies a 4.

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

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

Description clearly states verb 'Get' and resource 'ArcGIS Feature/Map Service layer's schema'. Lists specific returned information (fields, geometry type, record count, capabilities). Distinguishes from sibling tools like query_layer (queries data) and search_datasets (finds datasets) by focusing on schema retrieval.

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

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

No explicit when-to-use or when-not-to-use guidelines. Usage is implied by tool name and description (for obtaining layer schema). Does not mention alternatives like query_layer for data queries, thus leaving ambiguity for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that only active subscriptions are returned by default, providing marginal behavioral context beyond annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. Front-loaded, efficient, and without any wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context. No gaps remain.

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

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

Schema coverage is 100% with one well-documented parameter. The description reinforces the default exclusion of inactive subscriptions, adding slight context but no new semantic meaning.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists return fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not exclude alternatives but gives 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?

Beyond the annotations' simple false hints, the description discloses meaningful behavior: rate limiting ('5 per identifier per day'), non-metered usage ('free; doesn't count against your tool-call quota'), the daily digest/review process, and the claim_token-based follow-up mechanism. No contradiction with annotations.

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

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

The description is front-loaded with purpose and use cases, then exclusions, follow-up mechanics, and policy details. It is dense—around 160 words—but every sentence carries distinct value. Slightly long for a quick scan, though structure minimizes waste.

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

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

Given no output schema and minimal annotations, the description fully compensates: it explains the claim_token return value, how to use it later, the scope boundary (Pipeworx vs other servers), rate limits, quota behavior, and content expectations. This is complete for a feedback tool with nested context objects and optional parameters.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is high. The description adds practical guidance beyond the schema, such as the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), message specificity requirements, and context examples. This enhances but does not fully replace schema self-documentation.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names specific feedback types (bug, feature/data_gap, praise) and is easily distinguished from sibling tools like ask_pipeworx, which are for querying rather than submitting feedback.

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

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

Provides explicit when-to-use guidance for each feedback category and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also instructs users to describe issues in terms of Pipeworx tools and not paste end-user prompts.

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. Description adds: data source (CF analytics-engine), no PII, caching behavior (5min-1h). This fully discloses behavioral traits beyond annotations.

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

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

The description is two paragraphs with clear front-loading. The second paragraph lists use cases efficiently. Could be slightly tighter, but no wasted sentences.

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 read-only tool with one optional parameter, the description covers purpose, usage, data source, privacy, caching, and return values. No output schema needed as returns are described. Fully complete.

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

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

Schema coverage is 100% with enum description. Description adds semantic guidance: shorter windows for hot topics, longer for steady-state demand. This adds valuable meaning beyond schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with specific verb 'Returns' and resource 'top tools, top packs, total call volume'. It distinguishes from siblings like discover_tools by focusing on what other agents call, not general discovery.

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

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

Three concrete use cases are listed (hot data sources, confirming canonical tool, aligning use case). Mentions self-aggregating signal and caching. Does not explicitly state when not to use, but the context implies it's for trending analysis, not for specific search.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds significant behavioral details: algorithms used (monotonicity, partition-sum), semantic anchor (Jaccard similarity ≥0.30), partition filter (drop placeholder slugs >20%), fill check against CLOB depth, and response 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 lengthy but well-structured: overall purpose, mode explanations, algorithmic details, and response format. Every sentence adds value given the tool's complexity. Could be slightly more condensed without losing clarity, but it remains effective.

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

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

No output schema exists, but the description compensates by detailing the response structure (opportunities[] with gap_pp, suggested_trade, etc., and partition_check fields) and explaining fill-check behavior. Some details like result limits or error handling are absent, but overall coverage is strong for a complex tool.

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

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

Both parameters (event and topic) are fully described in the schema (100% coverage). The description adds substantial context: examples of event slugs ('fed-decision-may-2026'), acceptance of full Polymarket URLs, and explanation of topic as a seed question that triggers cross-event scanning. This enhances the schema descriptions.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains what each does, separating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides guidance on not trading when realizable_edge_pp ≤ 0, giving clear context for agent decision-making.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description far exceeds this by detailing caching ('Cached 1h at KV level'), response structure (by_segment, fed_candidates, _diagnostics), model families, placeholder filtering, edge calculation components, and internal thresholds. It also discloses limitations like Fed bets being excluded due to unreliable signal.

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

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

The description is well-structured with clear sections and headings, but it is very long and dense with technical details. It front-loads the purpose and usage but could be more concise by reducing redundancy or moving detailed model descriptions to a separate section. Still, every sentence adds value.

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

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

Given the complexity (9 params, no output schema), the description is remarkably complete. It explains the response structure, diagnostics, caching, internal thresholds, and even the 24h-move warning. It compensates for the missing output schema by detailing what each opportunity carries. No gaps identified.

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

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

Schema coverage is 100%. The description adds significant value beyond the schema by explaining the purpose and best practices for each parameter (e.g., 'tradeable-edge filter', 'bump for very thin partitions', 'Use to suppress thin partitions...'). It provides concrete examples and clarifies interactions like min_partition_leg_kelly not applying to parent-level Kelly.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses strong verbs like 'Scan' and 'return', explicitly distinguishes from siblings (e.g., polymarket_arbitrage) by noting it is built for 'what should I bet on today' without paging hundreds of markets.

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 primary use case: discovering opportunities without manual paging. It provides guidance on knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities') and explains when to adjust slippage_pp. It does not explicitly contrast with sibling tools, but the context of sibling names implies alternatives exist.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which are consistent with the description. The description adds substantial behavioral detail: return structure (tracked, expired, snapshot_dates), data sources, limitations (60-day TTL, daily closes), and derivation logic (trend, decay), going well beyond annotations.

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

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

The description is dense but well-structured: purpose, return details, limitations. It is front-loaded and each sentence earns its place given the tool's complexity. Could be slightly more streamlined but remains clear.

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 thoroughly explains the return arrays and their fields (tracked[], expired[], snapshot_dates[]) with example content and edge cases. Limitations are also covered, making the description complete for an agent to understand outputs and 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 repeats default values and maxima already in the schema but adds minor context on window families. No significant additional semantic value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration and shrinkage. It distinguishes itself from the sibling `polymarket_edges` by being a derived analysis tool, though it does not explicitly contrast 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?

The description implies usage for assessing edge longevity and trend, explicitly framing the question it answers. However, it does not provide explicit when-not-to-use scenarios or alternative tool comparisons, leaving some room for inference.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: walks order book ladder, returns fill prices, slippage, verdict, and for baskets, capture ratio, thin legs, forced directional risk, and warns about unhedged positions. No contradictions.

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

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

Description is lengthy but well-structured: starts with core purpose, then REQUIRES, then details both modes, outputs, usage note. Every sentence adds value; length is justified by tool complexity.

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

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

Covers all necessary aspects: purpose, modes, parameters, return fields (no output schema, so description provides all fields), usage guidance, and risk warnings. Annotations handle safety; description handles the rest.

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

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

Schema coverage is 100%, and description adds significant context: distinguishes market vs event modes, explains side defaults (auto for basket), clarifies size_usd interpretation (spend vs target proceeds, settlement notional), and notes clamp range 10-1,000,000.

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 checks realizable-vs-theoretical edge against order-book depth, distinguishing between single-market and basket modes. Explicitly ties usage to sibling tools polymarket_arbitrage and polymarket_edges, providing clear differentiation.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains consequences of not using it (partial fills leading to unhedged positions).

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description expands significantly: it explains compatibility warnings in two cases (non-equivalent bet shapes, semantically unrelated events), temporal alignment, skipped cross-type/subtype counters, and that real spreads are rare. No contradiction with annotations.

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

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

The description is well-structured with clear sections (two modes, response, safety fields) and uses emphasis (bold). However, it is lengthy and some parts (e.g., detailed safety field explanations) could be condensed. It's adequately concise but not maximally 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 the tool's complexity (cross-venue spread with multiple failure modes), the description is thorough. It covers modes, response structure, safety fields, and temporal alignment. There is no output schema, but the description explains what the response contains. Could mention rate limits or authentication, but overall complete.

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

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

Schema coverage is 100% with each parameter having a description. The description adds context about how topic overrides work and lists the exact topic values. However, it does not add substantial meaning beyond the schema's own descriptions; it mainly reinforces and explains. Baseline 3 is appropriate.

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

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

The description clearly states the tool computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains two distinct modes (topic and explicit) and details what the tool outputs. This differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on single-venue arbitrage or edge detection.

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 guidance on when to use topic mode (for 10 pre-mapped macros) vs explicit mode (custom pairings). It warns that most pre-mapped topics may return compatibility warnings, implying that explicit mode is safer. However, it does not explicitly compare to sibling tools or state when this tool should or should not be used over others.

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

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

Annotations already cover safety and idempotency. Description adds that it returns attribute rows and geometry, which is useful but not extensive. No contradictions with annotations.

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

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

Three sentences: purpose, parameter summary, usage tip. No fluff, front-loaded. Efficient and clear.

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

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

Covers purpose, parameters, and return type (attributes + geometry). Lacks description of response format or error handling, but acceptable given no output schema and rich 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?

All 6 parameters are fully described in the schema (100% coverage). The description reiterates the parameters with minimal additional context (e.g., 'SQL-like'). 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?

Clearly states it queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. However, it does not explicitly differentiate from sibling tools like search_datasets, which might be confused.

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 a specific usage tip ('Use where="1=1" + out_fields="*" to sample') but lacks guidance on when to avoid this tool or mention alternative tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds scoping details and dual-mode behavior (retrieve/list), complementing annotations without contradiction.

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

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

Three sentences, front-loaded with primary action, no wasted words. Every sentence adds value.

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

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

All necessary information for a simple tool: dual mode, scoping, pairing with siblings. No gaps given complexity and lack of output schema.

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

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

Schema coverage is 100% and schema already describes parameter behavior. Description restates the omit-to-list behavior but adds usage context, so baseline 3 is appropriate.

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

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

Description clearly states the tool retrieves saved values or lists keys, with specific verb-resource pairing. Distinguishes from siblings 'remember' and 'forget' by naming 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 tells when to use (look up context) and alternatives (remember to save, forget to delete). Provides examples and scoping information.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral details: the 'mark_read' parameter's effect on subsequent calls, the resource format of each alert, and the alternative HTTP endpoint. No contradictions with annotations.

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

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

The description is a single paragraph that is well-structured: it starts with the core purpose, then details return fields and filters, followed by behavior notes and an alternative access method. It is concise without being terse, though slightly verbose in listing alternatives.

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

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

Given the parameter count (5) and absence of an output schema, the description covers the essential aspects: what the tool returns (source, citation_uri, payload), how to filter, the 'mark_read' behavior, and polling compatibility. It lacks details on error scenarios or pagination hints, but is sufficient for most use cases.

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

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

The input schema has 100% coverage with descriptions. The tool description elaborates on key parameters, like giving an example for 'type' ('sec_8k') and explaining the 'mark_read' side effect. This adds practical meaning beyond the schema's brief descriptions.

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

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

The description uses specific verbs and resources: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It clearly identifies the tool's function and mentions key attributes like source and citation_uri. While it doesn't explicitly distinguish from siblings like 'list_subscriptions' or 'subscribe', the purpose is unambiguous.

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

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

The description provides context on available filters (type, since) and mentions that polls work fine. It also notes an alternative access method via a URL. However, it does not explicitly state when to use this tool vs other query or subscription tools, nor does it give exclusion conditions.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) indicate safety. The description adds significant behavioral context: parallel fan-out to multiple APIs, fallback logic, soft-fail for USPTO, accepted date formats, and the structure of the response (grouped changes, citations). This goes well beyond annotations.

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

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

The description is a single dense paragraph that front-loads with example queries, then details sources and format. While efficient and informative, it could benefit from slight structure (e.g., bullet points) for easier scanning. However, every sentence serves a purpose.

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

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

With three parameters, high schema coverage, no output schema, and rich annotations, the description fully equips an agent: it explains what the tool does, how to use parameters, what to expect in the response (structured changes, citations), fallbacks, and when to choose an alternative. No gaps remain.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by providing concrete examples for `since` ('7d', '30d', '3m', '1y') and a recommendation ('Use 30d or 1m for typical monitoring'), and clarifies `value` accepts ticker or CIK. This is meaningful guidance 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 directly states the tool provides a change feed for a company in a time window, with specific examples ('What's new with X', 'latest on Y'). It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from the sibling tool entity_profile, which provides static profiles. This is a specific verb+resource with clear differentiation.

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

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

The description gives explicit usage context with example queries, explains fallback behavior (GDELT→GNews), and provides a clear when-not-to-use directive: 'Use entity_profile instead when you want the static profile...' This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds key behaviors: key-value pair scoped by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. No contradictions.

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

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

Three sentences packed with essential information: purpose, usage guidance, behavioral details. Front-loaded with action verb and resource. No wasted words.

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

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

Given the tool has 2 simple parameters, no output schema, and annotations cover safety, the description fully covers persistence, scoping, and pairing with siblings. 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 good descriptions for key and value. Tool description adds little beyond what schema provides, but baseline is 3. No extra parameter context 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?

Description clearly states the tool saves data for later reuse across conversations or sessions, with specific examples (resolved ticker, target address) and explicitly distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Provides examples of use cases and pairs with recall and forget, giving clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the base safety profile is known. The description adds valuable behavioral context: it can auto-disambiguate input (e.g., ticker, CIK, or company name), returns specific citation URIs, and 'cascades through several lookup endpoints internally.' These details go beyond the annotations and inform the agent about the tool's internal process and output richness. 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?

Although the description is relatively long, it is tightly structured and every sentence serves a purpose. It begins with attention-grabbing example queries, then states the core purpose, provides a clear usage directive, lists supported types with detailed output descriptions, and concludes with an efficiency note. The information is front-loaded and the formatting with 'SUPPORTED TYPES' aids readability. 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?

The tool is moderately complex with no output schema, so the description must explain return values and behavior. It does so comprehensively: it describes outputs (ticker, CIK, RxCUI, ingredient, brand), citation URIs, accepted input formats, and internal cascading. It also clarifies the tool's role relative to other tools. This is complete for the agent to select and invoke the tool correctly without needing additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description significantly enriches parameter understanding: for 'type' it details what each enum value returns (ticker + CIK + company_name for company; RxCUI + ingredient + brand for drug) and for 'value' it specifies accepted input formats with examples. This is far more than the schema's bare-bones descriptions, adding crucial semantic meaning about outputs and accepted formats.

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: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete examples of natural language queries (ticker, CIK, RxCUI, ID) and clearly distinguishes it from sibling tools like entity_profile by focusing on lookup of identifiers rather than profiling or comparison. The verb+resource structure is specific and unambiguous.

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

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

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool's efficiency advantage ('replaces 2-3 manual lookups') and enumerates supported entity types, making it clear when to invoke it. While it doesn't explicitly say 'when not to use,' the strong 'Use FIRST' instruction and the contextual benefits provide clear guidance over 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 readOnly and idempotent behavior. The description adds that it probes each entity with ai_visibility_check and ranks results, which is sufficient. 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?

Two sentences plus an example use case. Information is front-loaded and every sentence adds value. 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?

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density). It covers the probing mechanism and all parameters. Complete for a tool with 4 params and 1 required.

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

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

Schema coverage is 100%, but the description adds useful context beyond schema: first entity is subject, rest competitors, and context disambiguates common names. This supplements the schema effectively.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check, and returns a ranked list. It distinguishes from the sibling 'ai_visibility_check' by focusing on side-by-side comparison.

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

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

The description explicitly mentions use case: competitive AI-marketing audits, and gives an example. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or alternatives.

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

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

Beyond annotations, description adds critical behavior: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts. 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?

Single dense paragraph, front-loaded with purpose, every sentence adds value. No wasted words.

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

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

Given tool complexity (composite, multiple outputs), description covers return fields, failure modes, timing, and ecosystem scope. Complete for agent decision-making.

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

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

Schema has 100% coverage; description adds meaning by explaining 'package' accepts scoped names and 'version' defaults to latest. Provides usage context beyond schema.

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

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

Description clearly states it's a composite check for adding npm packages, fans out to multiple services, and distinguishes from siblings (NPM only in v1, other ecosystems use deps.dev:version).

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 ('is X safe/popular/small', 'what does adding lodash cost me'). Implicitly suggests alternatives for non-NPM ecosystems. Lacks explicit when-not-to-use but overall 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, idempotentHint, etc. The description adds value by specifying the return fields (name, summary, record_count, owner/org, url) and the expected workflow, enhancing transparency beyond annotations.

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

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

Two concise sentences: first defines purpose with examples, second lists return fields and next steps. Front-loaded and free of fluff.

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

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

Covers search scope, return fields, and next steps. No output schema exists, so description fills the gap. Lacks edge-case handling but is sufficient for typical use. With rich annotations, completeness 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 descriptions for all three parameters. The description adds minimal new parameter info beyond 'by keyword' but does describe return structure, which compensates slightly. 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?

The description clearly states the tool searches City of Tucson GIS open geospatial datasets by keyword, lists example categories, and distinguishes from siblings by specifying to pass the returned url to query_layer or layer_info.

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 (search by keyword) and provides follow-up actions (pass url to query_layer/layer_info). It does not explicitly state when not to use, but given sibling context, it is clear this is for dataset discovery.

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 underlying embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and truncation behavior (200K limit, flagged). Annotations confirm read-only, idempotent, non-destructive nature.

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?

Five sentences with no wasted words; core information front-loaded. Every sentence contributes essential context.

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

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

Despite lacking an output schema, the description sufficiently explains the return format (passages with offsets and scores), constraints, and integration with other tools. No major information 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 already has 100% description coverage for all 3 parameters. Description reinforces with examples of query types ('supply-chain risk', 'fiscal year 2024 revenue'), adding practical guidance beyond schema.

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

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

The description clearly defines the tool as performing semantic search inside a user-provided text, specifying the input (text and query) and output (passages with offsets and scores). It distinguishes from siblings like 'ask_pipeworx' and 'ask_pipeworx_grounded' by highlighting the local search capability and pairing with the grounded variant.

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

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

Explicitly states when to use (when record is too large for prompt) and how it complements 'ask_pipeworx_grounded'. Also mentions the 200K character limit and truncation behavior.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context such as OAuth requirement, SMS cap, webhook signing, and auto-disable after failures. The idempotency behavior is not discussed despite idempotentHint=true, but the description 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 front-loaded with purpose and prerequisites, then systematically covers types and delivery. Each sentence adds value. It is somewhat lengthy but well-organized; minor reduction in verbosity for the delivery section could improve conciseness.

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

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

The description explains the return value (new subscription id) and covers all subscription types and delivery channels in detail, including constraints like SMS cap and webhook signing. Missing aspects include error handling and explicit idempotency behavior, but overall it is highly informative for a no-output-schema tool.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly enriches each parameter: for 'type' it gives real-world examples (e.g., items:['5.02'] = officer change), for 'params' it provides complete structures per type, and for 'delivery' it explains the behavior of each channel (e.g., webhook signing secret returned once, auto-disable after 10 failures). This far exceeds the schema's minimal descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription' and specifies the return of 'the new subscription id', establishing a specific verb-resource pairing that distinguishes this tool from siblings like list_subscriptions and unsubscribe.

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

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

The description provides clear prerequisites (Pipeworx OAuth account) and explains when each subscription type is appropriate with examples. However, it does not explicitly contrast with sibling tools or state when not to use this tool, leaving some inference to the agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns live catalog example questions with tool shapes, which is useful context 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?

Description is well-organized, starting with typical user queries, then explaining purpose, categories, and usage. Front-loaded with key information. Slightly long but every sentence is substantive.

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

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

Given the complexity of an onboarding tool with many categories and no output schema, the description adequately explains what is returned (category-bucketed examples with tool shapes) and how to use it, providing a complete picture for the 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 provides 100% coverage for the single optional parameter 'topic' with a description. The description adds example values ('finance', 'pharma', 'betting') and clarifies the effect, adding 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's the onboarding entry point for an agent to learn what Pipeworx can do. Uses specific verb 'returns category-bucketed example questions' and differentiates from sibling tools like ask_pipeworx by indicating when 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?

Explicitly says to use this tool when the agent doesn't know what Pipeworx can do, and provides guidance on calling with no arguments for full spread or passing a topic to focus. Does not explicitly mention when not to use, but context from sibling tool list implies alternatives.

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

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

Adds value beyond annotations by explaining ownership enforcement and deactivation (not deletion), linking to 'recent_alerts'. Annotations already flag idempotent and non-destructive; description enriches.

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

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

Two sentences, no wasted words. Front-loaded with action and key constraints.

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

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

For a simple one-parameter tool with no output schema, description covers purpose, ownership, side-effects, and relation to other tools adequately.

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 parameter 'id' fully (100% coverage). Description does not add further meaning beyond schema, meeting baseline expectation.

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

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

Uses specific verb 'Cancel' and resource 'subscription'. Clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by describing the action and effect.

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

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

States when to use (cancel subscription by id) and mentions ownership enforcement. Provides clear context but lacks explicit when-not-to-use or 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the two-path processing (SEC EDGAR vs. grounded pipeline), the output format (verdict, actual value with citation, reasoning), and the tolerance mechanism. No contradiction with annotations.

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

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

The description is well-structured with examples, breakdown of processing paths, and output details. Every sentence adds value, and the length is justified by the complexity of the tool. No wasted words.

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

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

Given the tool's complexity (two parameters, no output schema, but rich annotations), the description provides a complete picture: it explains the two processing paths, the output verdict types, citation format, and reasoning. It covers both company-financial and other claims comprehensively.

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

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

Schema coverage is 100% for both parameters. The description does not add significant detail beyond the schema; it restates the purpose of 'claim' and 'tolerance_pct' without new semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides explicit invocation examples (e.g., 'Is it true that…', 'fact check') and distinguishes itself from siblings by noting it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other claims, guiding the agent on which processing path to expect. However, it does not explicitly list alternative tools or 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.