Arcgis Sanjuannm

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: default model (Workers AI Llama-3.3-70b), optional Anthropic probing with BYO key, cost implications, and return structure. This goes beyond what annotations provide.

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

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

Description is concise (3 sentences) and front-loaded with the main action. It efficiently covers purpose, usage, parameters, and return value without superfluous 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?

No output schema, but description adequately describes return values (per-model score, confidence, signals, raw_response + combined view). Given complexity (4 params, multiple models, optional auth), the description is complete and informative.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning by explaining the default model, how _apiKey is used, and the purpose of 'context'. This complements 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?

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility, with a specific verb 'probe' and resource 'LLMs'. It distinguishes from sibling tools by its unique function and output format.

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

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

Description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not explicitly say when not to use or list alternatives, but the use cases are clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond these: it routes to thousands of tools, fills arguments, works on every tier, and is 'one fast call.' It also explains it covers live news and '*news-feeds packs.' While it doesn't disclose every behavior (e.g., potential delays), it enriches the behavioral profile without contradicting annotations.

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

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

The description is long but well-structured, front-loaded with the critical 'PREFER OVER WEB SEARCH' directive, followed by how it works, when to use, examples, and alternatives. Each sentence adds value; there is no fluff. Slightly verbose but appropriate for a high-stakes default entry point.

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

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

Given the tool's complexity (routing to thousands of sources), the description is remarkably complete. It covers purpose, usage, examples, exclusions, and alternatives. It mentions citation URIs and counts of sources, and addresses breaking news via note. No output schema exists, but the description sufficiently informs what the agent will get. The sibling list is large, yet key differentiators are named.

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 single meaningful parameter 'question' is described as 'Your question or request in natural language' with aliases listed. The description adds examples of questions, which are helpful, but the schema already includes an examples array. Thus the description provides marginal extra 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 a specific verb+resource: it 'routes the question to the right one of 5,529 tools across 1455 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' This distinguishes it from siblings like ask_pipeworx_grounded and deep_research by explicitly positioning it as the default entry point for factual questions.

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

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

The description provides explicit when-to-use guidance: 'START HERE for most questions' and 'Use whenever the user asks...' with trigger phrases and examples. It also gives when-not-to-use conditions and alternatives: 'Step up only when needed: for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is textbook usage differentiation.

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

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

Adds significant context beyond annotations: beta status, candidate routing improvements enabled live, comparison against the stable router, and the current inactive candidate. It also states that results are compared to decide merges, which is useful behavioral detail. However, it doesn't elaborate on potential differences in output quality or edge cases, so a 4 is appropriate.

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

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

The description is 4 sentences, front-loaded with the core purpose ('Beta version of ask_pipeworx'). Each sentence adds necessary information: status, current state, usage guidance, and clarification that it's a full working router. 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 is a beta variant of an existing sibling, the description adequately references 'same response shape' and 'same arguments' to link to ask_pipeworx. It also explains the experimental nature and current stability. However, it doesn't provide an example or detail the response structure, relying on prior knowledge of ask_pipeworx, so it falls just short of a 5.

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

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

The schema already covers all parameters with 100% coverage, including aliases and a clear description for the required 'question'. The description provides no additional parameter meaning beyond what the schema already gives, so it earns the baseline 3.

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

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

Clearly identifies the tool as 'Beta version of ask_pipeworx' and describes it as a 'universal router', distinguishing it from the stable sibling by the beta/experimental label. It explicitly states the exact relationship to ask_pipeworx, making the purpose unambiguous.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and names the stable alternative (ask_pipeworx). It also clarifies that the tool is fully functional and not a fallback, so agents know when to choose it over the stable version.

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

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

Discloses key behavioral traits beyond annotations: it extracts answers only from tool results, returns structured success/refusal formats with specific reasons, and costs an extra LLM call. This adds significant context about reliability and failure modes, complementing the readOnly/openWorld/idempotent 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?

The description is dense but efficient, front-loading the core purpose, then detailing behavior and usage guidance. Every sentence serves a distinct function (purpose, mechanics, return format, use cases), with 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, the description is remarkably complete: it covers the routing mechanism, return shape, refusal reasons, cost implication, and appropriate usage contexts. No output schema is needed because the description fully specifies the response format.

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

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

Schema coverage is 100%, with all six parameters being aliases for the same 'question' string. The description does not add parameter-specific semantics beyond what the schema already provides, so the baseline score of 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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb 'ask' and a grounded extraction behavior. It explicitly differentiates from sibling tool ask_pipeworx by noting the grounded extraction and refusal mechanism.

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 this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). Names the alternative tool and explains the cost tradeoff, providing clear decision 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: resolver contract (market_match_confidence, alternatives), parent event extractor, news field fallbacks, safety short-circuits for low-confidence or closed markets, wide-spread warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is very long and detailed, packed with examples, classifiers, fan-out patterns, response shapes, and edge cases. While comprehensive, it could be more concise and better structured (e.g., bullet points or sections). It front-loads the core purpose, but the density may overwhelm an agent.

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

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

Given the tool's complexity—multiple data sources, classification, parallel fan-out, resolver logic, parent events, news fields, safety checks, market statuses, liquidity, and resolution rules—the description covers all these aspects thoroughly. No output schema exists, so the description fully explains return values, making it complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description adds further context: explains that 'market' accepts slug, URL, or question text; elaborates on 'depth' (quick vs thorough default thorough) and 'include_raw' (false recommended). This adds meaning beyond the schema, especially for the 'market' parameter.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The 'Use for' clause distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage, making its 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?

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes classifier and fan-out examples, giving agents clear context. However, it does not explicitly state when not to use or name alternative sibling tools, though the purpose itself differentiates.

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

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

Description adds significant context beyond annotations: specifies data sources (SEC EDGAR for companies, FAERS for drugs), mentions off-calendar fiscal year handling, result sorting by primary metric, and output including citation URIs. Annotations already declare readOnly, idempotent, openWorld; description enriches with operational details.

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 starts with key trigger phrases, then purpose, then parameter details, then output info. Every sentence adds value, though slightly lengthy - could be more compact but efficient enough.

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 two parameters, no nested objects, and annotations covering safety, description explains what each type returns and the output (paired data + citation URIs). Lacks explicit output structure but sufficient for understanding; sibling tool entity_profile fills single-entity gap.

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

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

Schema coverage is 100% so baseline is 3, but description adds value by explaining what each enum value means (company vs drug data details) and gives examples for values (tickers/CIKs for company, drug names). Adds nuance like off-calendar fiscal year handling.

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 side-by-side comparison of 2-5 companies or drugs in one parallel call, using trigger phrases like 'compare X and Y' and explicitly distinguishes from sequential lookups.

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

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

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8-15 sequential lookups, providing clear usage context. Could explicitly mention when not to use (e.g., for single entity queries) but implied by contrast with siblings like entity_profile.

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 read-only/open-world annotations, the description discloses account requirements, paid tier for 'thorough', expected latency (15-60s, up to 90s), never-invented gaps[], citation_uri fetchability, contradictions for certain depths, and semantic excerpting. 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 long but every sentence carries essential information. It is front-loaded with account requirements and alternatives, then purpose, usage guidance, depth mechanics, output semantics, and latency. There is 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?

With no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions, and hop field. It also covers depth behavior, failure modes, and performance expectations, making it highly complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by noting that 'thorough' requires a paid plan, giving expected latencies per depth, and providing example questions. This extra context is valuable but not critical.

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 function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition and parallel routing. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making its scope and uniqueness 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?

Extensive when-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides best-case examples and explains depth-level trade-offs.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that results include names, descriptions, full schemas with curated examples, and are ready to call directly, which goes beyond annotation coverage.

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

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

Description is well-structured with front-loaded purpose and examples. Could be slightly more concise, but every sentence earns its place in providing clarity and 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?

Despite no output schema, the description fully explains return value (top-N tools with names, descriptions, full schemas, examples) and limit details. Completeness is high for a discovery tool with clear inputs and outputs.

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

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

Schema description coverage is 100% with detailed parameter descriptions (query, q, task, limit, etc.). The description restates alias information already present in the schema, so adds marginal value beyond schema.

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

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

The description clearly states it finds tools by describing data or task, listing many domains (SEC filings, financials, FDA drugs, etc.) and explicitly distinguishes from sibling tools by being the discovery entry point.

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

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

Explicitly instructs to call this FIRST when many tools are available and to see the option set. Also provides usage context for browsing/searching/discovering across specific categories.

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

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

Adds significant context beyond annotations: fans out across multiple data sources, notes patent search soft-fails until reactivated, and describes fallback logic. Consistent with readOnly and idempotent hints.

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 efficient; front-loaded with example queries and structured bullet points. Every sentence adds value, though slightly dense.

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

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

Thoroughly covers return fields (CIK, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). Adequate given no output schema.

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

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

Schema coverage is 100% with clear descriptions. Description reinforces with examples (AAPL, CIK) and reiterates that names are not supported, adding marginal but useful clarity.

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

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

Description clearly states it retrieves a holistic cross-source profile of a US public company in one call, with specific examples ('Tell me about X'). Distinguishes from chaining single-source lookups and mentions sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over chaining...' for holistic views and directs users with only names to use resolve_entity first, providing both usage context and alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not clarify idempotency behavior (e.g., what happens if key is missing). This is adequate but not fully transparent.

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

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

Two sentences, front-loaded with the action. Every sentence is purposeful with no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and pairing with siblings. It is complete and sufficient.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb 'delete' and resource 'memory by key'. It effectively distinguishes from siblings '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?

The description explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall', providing clear usage direction.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. This clarifies the process without contradicting annotations.

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

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

Four sentences, each essential: function, process, output format, use cases. No wasted words, 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?

Describes output format clearly despite lack of output schema. Parameters well-covered. Could mention error handling or URL validation, but not required given the tool's simplicity.

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?

Parameter descriptions in the schema cover both url and max_links sufficiently (100% coverage). The tool description reinforces these but adds limited new detail beyond the schema, 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 it generates an llms.txt file for any URL to enable AI crawler indexing. It specifies a concrete outcome (a text blob for site-root/llms.txt) and differs from siblings like ai_visibility_check or scan_competitor_ai_presence.

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

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

Explicitly lists three use cases (client indexing, own project, competitor auditing). While it doesn't contrast directly with siblings, the use cases are specific enough to guide 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context by listing the specific schema attributes returned (fields, geometry type, record count, capabilities). This goes 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 a single well-structured sentence that front-loads the verb and resource, then enumerates the return details. Every word is purposeful; there is no redundancy or extraneous content.

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

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

Given the simplicity of the tool (one parameter, clear annotations, no output schema), the description sufficiently explains what the tool returns and its purpose. It could optionally mention any limitations (e.g., supported service types beyond ArcGIS Server) but is complete enough for effective use.

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

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

Schema coverage is 100% (one parameter with description). The description's mention of 'url' adds no new meaning—the schema already states it is a 'Feature/Map Service layer url'. No additional parameter semantics are provided beyond the schema.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource (ArcGIS Feature/Map Service layer's schema) along with the exact details returned (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like 'query_layer' which retrieves data.

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

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

The description implies the tool should be used when obtaining schema information about a layer, but it does not explicitly state when to use this tool over alternatives or mention any exclusions or prerequisites. Usage context is implied but not fully specified.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description adds value by detailing the response structure and default filtering (active subscriptions only), but does not mention auth or rate limits.

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

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

The description is two sentences, front-loaded with the core action and return fields, followed by usage guidance. No redundant or extraneous information.

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

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

Despite no output schema, the description enumerates the return fields and default behavior. Combined with comprehensive annotations, it provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100%, and the input schema already explains the 'include_inactive' parameter clearly. The main description adds no additional parameter meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the exact fields returned. It differentiates from siblings like subscribe and unsubscribe by framing the tool for review before adding or canceling.

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 it: 'review what you're monitoring before adding more or to find an id to cancel'. This provides direct guidance on appropriate usage scenarios.

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

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

Annotations are all false, so the description carries full responsibility for behavioral disclosure. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow for later retrieval, the fact that it's free, and that the team reads feedback daily. This is comprehensive for a feedback tool and goes well beyond the minimal safety flags.

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

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

The description is longer than average, but every sentence carries operational weight: use-cases, scope exclusions, claim_token mechanics, rate limits, and cost. It is front-loaded with purpose and follows a logical flow from 'what' to 'when' to 'how.' Slight wordiness (e.g., motivational note about roadmap) is acceptable given the tool's complexity.

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

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

There is no output schema, so the description must explain return behavior. It does so by stating that filing returns a claim_token and that passing it back later allows reading the status. Combined with coverage of prerequisites, exclusions, and rate limits, the description fully equips an agent to use the tool correctly without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising how to frame the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches parameter understanding beyond the schema's per-field 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by explicitly limiting scope to 'tools served by this Pipeworx connection' and enumerating the feedback types (bug, feature, data_gap, praise).

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

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

The description provides explicit when-to-use guidance via examples ('Use when a tool returns wrong/stale data (bug)…') and equally explicit when-not-to-use exclusions ('if the tool came from a different MCP server… file it with that server instead'). It also tells the agent to describe issues in terms of Pipeworx tools and not paste 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 readOnly and idempotent hints. The description adds valuable behavioral context: caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). No contradiction with annotations.

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

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

The description is concise (4 sentences) with front-loaded purpose. Every sentence adds value—no fluff. Structure flows from purpose to use cases to behavioral notes.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete. It covers purpose, usage scenarios, behavioral traits, and data source. All essential information is present.

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

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

Schema coverage is 100% with a clear enum description. The description adds nuance by explaining that shorter windows show hot trends and longer windows show steady-state demand, going beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. The phrase 'what other AI agents are calling on Pipeworx right now' provides a specific verb and resource, distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Three explicit use cases are provided (discovering hot sources, confirming canonical tools, seeing alignment). While there are no explicit 'when not to use' statements, the guidance is clear and sufficient for deciding to invoke this tool.

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

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

Annotations already indicate readOnlyHint=true, and the description adds detailed behavioral traits: it describes fill check with live CLOB depth, semantic anchor using Jaccard similarity, partition filter for placeholders, and explains when not to trade. No contradictions.

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

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

The description is somewhat lengthy but front-loaded with the essential purpose and modes. Every sentence adds value, covering modes, response structure, and edge cases. A minor improvement could be to break into shorter paragraphs for readability.

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

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

Given the tool has no output schema, the description fully explains the response structure (opportunities array with fields, partition_check details, fill check logic). It covers edge cases like skipped_low_similarity and placeholder filtering, and references a sibling tool for custom sizing.

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, but the tool description adds substantial meaning: for event, it explains the partition check and ordering checks; for topic, it explains cross-event scanning, Jaccard similarity, and placeholder filtering. This goes far 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools by specifying these unique methods and modes (event, topic, trending_scan).

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

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

The description explicitly advises when to use each parameter: no args for trending_scan, event for specific markets (recommended), topic for cross-event scans. It also recommends polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: cache TTL (1h at KV level keyed on knobs), detailed model families, edge calculation, slippage handling, and response structure including diagnostics. No contradictions. Adds significant value 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 fairly long but well-structured, front-loaded with purpose and key concepts. Each section adds value, though it could be more concise. Still, the structure aids understanding.

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

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

Given the tool's complexity (9 parameters, three model families, detailed response), the description covers all essential aspects: model explanations, edge calculation, knobs, response top-level and diagnostics. No output schema is needed as the description explains return values. Complete for the task.

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 detailed descriptions for each parameter. The description provides a high-level overview of knobs but does not add significant per-parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, and gives a use case ('what should I bet on today'). However, it does not explicitly differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', so it falls short of a 5.

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 discovering betting opportunities and mentions the tool is built for that purpose. It provides context on when to use (agent discovering opportunities without paging) but lacks explicit when-not-to-use or alternatives. Hence, 4.

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

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

The description adds substantial behavioral context beyond annotations: data source (daily snapshots, not intraday), limitations (60-day TTL, snapshot gaps), response structure (tracked, expired, snapshot_dates), and meaning of fields (first_seen, trend, decay_pp_per_day, lifespan_days). No annotation contradiction.

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

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

The description is somewhat long but every sentence adds value: purpose, response breakdown, and limitations. It is well-structured and front-loaded with the core question. Minor redundancy could be trimmed.

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

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

Despite no output schema, the description explicitly details the structure of tracked, expired, and snapshot_dates arrays, including field meanings and computation. This provides complete guidance for an agent to interpret results.

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

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

Schema coverage is 100%, so the schema already documents both parameters (days, window). The description reiterates defaults and allowed values but adds no new semantic meaning. 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 that the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on historical trend analysis.

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

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

The description gives strong usage context by contrasting fresh vs. old edges, and explains when to use (for historical persistence) and implicitly when not (e.g., for intraday data). It does not explicitly name alternative tools, but the context is clear enough for selection.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details behavioral traits like ladder walking, return fields (verdict, thin_legs, forced_directional_risk), and the risk of partial basket fills converting arb into unhedged directional positions. 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 somewhat long but well-structured with key phrases in ALL CAPS (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) for quick scanning. Every sentence adds value, though slight trimming could improve conciseness.

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

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

Given no output schema, the description enumerates all return fields for both modes, explains input constraints, and provides usage context. It covers complexity well, leaving no critical gaps for an agent to understand 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% (baseline 3), but the description adds significant context: explains size_usd semantics for buys vs sells and basket settlement notional, side default logic for basket (auto from partition sum), and mode selection (market vs event). This goes well beyond the schema descriptions.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from siblings by advising use before polymarket_arbitrage or polymarket_edges for trades above ~$500.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books not capturable, partial fills create directional risk).

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

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

The description extensively details behavioral traits beyond annotations: compatibility warnings for non-equivalent bet shapes, temporal alignment, and skipped cross-type/subtype counters. Annotations indicate read-only and idempotent, which the description supports. No contradictions.

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

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

The description is detailed but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds value, though it is slightly longer than necessary.

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 compatibility warnings, temporal alignment, and multiple modes) and no output schema, the description provides comprehensive behavioral information, covering return format, safety fields, and counters. It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant context: lists the 10 topic shortcuts, provides examples for explicit tickers, and explains that explicit tickers override the topic-mapped side. This adds meaning beyond the schema.

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

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

The description clearly states the tool calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and describes the output. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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

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

The description explains when to use each mode (pre-mapped topics vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, so they are not tradeable. It lacks explicit guidance on when not to use (e.g., single-venue analysis) but provides sufficient context for decision.

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 no destructiveness, so the description's main behavioral contribution is clarifying that it returns attribute rows and geometry, and the SQL-like parameter behavior. No contradictions.

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

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

Two sentences with no waste. Front-loaded with the main action and input source, then concise parameter descriptions. Every sentence earns its place.

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

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

Given 6 parameters, 100% schema coverage, and no output schema, the description covers the tool's purpose, input, and behavior. It mentions return type (attributes and geometry) but could be slightly more explicit about error handling or output format. Still, it is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that parameters are SQL-like (where, order_by) and comma-separated (out_fields), plus provides examples, which enhances understanding beyond the schema descriptions.

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

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

The description clearly states it queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. The verb 'query' and resource 'layer' are specific, and it distinguishes from siblings like search_datasets (which finds datasets) by specifying the input comes from search_datasets.

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

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

It explicitly says the URL should come from search_datasets, and shows example usage including sampling with '1=1' and '*'. However, it does not explicitly mention when not to use this tool versus other siblings like search_within, though the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds: scoped to identifier, listing mode when key omitted, pairing with remember/forget. No contradiction.

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

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

Three sentences, front-loaded with main action, no wasted words. Efficient and well-structured.

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

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

No output schema, but description indirectly covers return behavior (retrieve value or list keys). Also addresses scoping and pairing. Minor gap: does not specify behavior on missing key.

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 largely echoes schema: 'Retrieve a value... or list all keys (omit the key argument).' No additional semantic depth beyond what schema provides.

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

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

Clear verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. Differentiates between two modes and implicitly distinguishes from siblings remember and forget.

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

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

States when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Scoped to identifier. No explicit when-not, but context is clear for a simple retrieval tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds valuable behavioral details: return fields (source, citation_uri, raw payload), the effect of mark_read on subsequent calls, and the availability of the same data via a REST 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 concise (approximately 80 words), front-loaded with the main action, and every sentence serves a purpose: main function, return data details, filtering options, mark_read effect, and alternative access method. No redundant phrases or fluff.

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

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

For a read-only, idempotent tool with five optional parameters and no output schema, the description covers all needed context: what it does, what it returns, how to filter, how to manage read state, and an alternative endpoint. Given the annotations already cover safety, 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%, baseline 3. The description adds meaning by explaining that 'type' filters by subscription type (e.g., 'sec_8k'), 'since' expects an ISO timestamp, and 'mark_read:true' flags events as read so next calls show only newer ones. It does not elaborate on 'limit' or 'unread_only', but the schema descriptions suffice. The added explanation raises the score above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed', clearly specifying the verb and resource. It further details the returned data including source, citation_uri, and raw event payload. The title 'Recent Alerts' aligns well. While not explicitly contrasting with siblings, the purpose is distinct from subscription management tools like list_subscriptions and subscribe.

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 filtering by type and since, and explains the mark_read flag for polling. It also notes the alternative GET endpoint for scripts and dashboards. However, it does not explicitly state when not to use this tool or compare it to sibling tools like search_within or ask_pipeworx.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds beyond this: it fans out to multiple sources in one parallel call, describes fallback between GDELT and GNews, notes USPTO soft-failure, and details the return 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 dense but well-structured: opening with examples, then a concise summary of function, followed by source details, parameter explanation, return type, and alternative tool. No redundancy; every sentence adds essential information.

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

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

With 3 parameters and no output schema, the description covers return structure (changes grouped by source, total_changes, citation URIs) and data source behaviors. Minor gaps: exact case sensitivity for 'value' not specified, but overall sufficient for correct use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'since' format with examples and typical usage, clarifying that 'value' accepts ticker or CIK, and confirming 'type' is limited to 'company'. This extra context justifies a score of 4.

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

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

The description clearly states the tool returns a change feed for a company over a time window, with examples like 'What's new with X'. It explicitly distinguishes from sibling 'entity_profile' for static profiles, ensuring no confusion.

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

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

The description provides explicit when-to-use scenarios (e.g., 'What's new with X') and when-not-to (static profile → entity_profile). It offers guidance on parameter values ('Use 30d for typical monitoring') and explains fallback behavior and limitations, aiding correct invocation.

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

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

The description adds significant behavioral context beyond the annotations: data is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations (idempotentHint: true, destructiveHint: false) are consistent and not contradicted.

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?

Every sentence contributes meaningful information. The description is front-loaded with purpose, then provides usage guidelines, followed by retention details and pairing. No filler or redundant phrases.

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

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description covers all necessary aspects: what it does, when to use, how data is stored, retention, and related tools. 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?

While the input schema already documents both parameters with good descriptions (100% coverage), the description adds value by explaining naming conventions (e.g., 'subject_property', 'target_ticker') and the flexible nature of the value ('any text'). This reinforces 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 a specific verb ('save data') and resource ('key-value pair'), and clearly distinguishes from sibling tools like recall and forget. It explains the tool's purpose in a way that an AI agent can immediately understand.

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 the tool ('when you discover something worth carrying forward'), gives concrete examples (resolved ticker, target address, user preference, research subject), and mentions pairing with recall/forget for a complete workflow. It also clarifies scoping and retention policies.

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

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

The description discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling for each identifier, and explicit handling of unresolved identifiers under `unresolved`. These behaviors go beyond the annotations (readOnlyHint, idempotentHint) and give important context about reliability and failure modes.

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 and dense, but well-structured: opening examples, purpose, usage guidance, supported types with details, degradation behavior, and a summary benefit. Every sentence provides useful information, though the opening examples could be condensed slightly to improve scannability.

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 carries the full burden of explaining return values and behavior. It describes the exact identifiers returned for each type, unresolved handling, source labeling, graceful degradation, and the fact that it replaces multiple manual lookups. This is comprehensive for a tool of this complexity.

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

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

The schema already documents the `value` parameter well, but the description adds semantic meaning to the `type` parameter by explaining what each type returns (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand). This adds value beyond the schema's simple enum description.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific verb 'resolve' and resource 'entity'. It distinguishes itself by listing example queries and positioning it as the first stop when a name needs an ID, differentiating it from sibling tools like entity_profile or compare_entities.

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

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

It explicitly instructs to 'Use FIRST whenever you have a name but need an ID' and provides numerous example queries. However, it does not explicitly name alternative tools or state when not to use it, so it misses a small part of the 'when-not/alternatives' guidance.

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

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

Annotations already indicate safe, read-only behavior (readOnlyHint, idempotent, non-destructive). Description adds that it probes with ai_visibility_check and returns score, confidence, signal density, which is useful 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?

Three sentences, front-loaded with purpose. Every sentence contributes value: purpose, method, use case, return format. 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 no output schema, description adequately explains return fields (ranked list, score, confidence, signal density). Could mention behavior on invalid entities or model-specific prerequisites, but overall complete for a read-only aggregator.

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 little beyond schema; it mentions 'your brand + N competitors' but schema already describes entities and first entry treatment. No additional parameter 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 the tool compares AI visibility across multiple entities, uses a specific verb 'compare' and resource 'AI visibility', and differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general compare).

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

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

Provides explicit context for competitive AI-marketing audits with an example question. Does not explicitly state when not to use or name alternatives, but the purpose implies exclusion for single-entity queries.

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, destructiveHint=false. The description adds significant behavioral context: partial failure handling, bundlephobia latency (5-30s first measurement), and sources_failed reporting. No contradictions.

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

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

The description is dense yet efficient, front-loading the core purpose, then detailing data sources, use cases, ecosystem limits, and behavioral notes. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description thoroughly explains the return content (summary block, per-advisory, links, alternative versions), ecosystem constraints, partial failure behavior, and latency. Completely covers what an agent needs.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds extra context (scoped packages accepted, version defaults to latest) which enhances understanding 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 explicitly states it is a composite check for evaluating adding an npm package, listing data sources (deps.dev, bundlephobia) and their outputs. It clearly distinguishes itself from sibling tools like deep_research by specifying the exact use case.

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

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

The description provides clear when-to-use examples ('is X safe / popular / small', 'what does adding lodash cost me') and notes ecosystem limitations (NPM only) with alternatives for other ecosystems (deps.dev:version).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the output structure (name, summary, record_count, etc.) and the url usage, but no additional behavioral traits beyond what annotations provide.

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

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

The description is two sentences: the first states purpose and scope, the second states output and usage. No filler, front-loaded, 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 no output schema and only 3 parameters, the description provides enough context: what the tool does, what it returns, and how to use the result. It could mention the default limit, but the schema covers that.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add parameter-specific details beyond the schema; it only mentions searching by keyword, which aligns with the query parameter.

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 'Search San Juan County GIS open geospatial datasets... by keyword' and lists example categories. It distinguishes the tool from siblings by mentioning that the output includes a url for use with query_layer/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 provides a clear use case: search for datasets by keyword and then use the returned url with query_layer/layer_info. It implies when to use this tool (to discover datasets) but doesn't explicitly state when not to use it.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds technical details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character cap (200K chars) with truncation and flagging. No contradictions with annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Each sentence earns its place: purpose, usage guidelines, technical details. No extraneous information.

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

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

Given the tool's complexity (3 parameters, no output schema), the description adequately explains return values (top-N passages with offsets and scores) and handles limits (200K chars, default limit). It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all three parameters described). The description adds value by providing examples for the query parameter, clarifying the limit range and default, and restating the max chars for text. This goes beyond the baseline of 3 expected for full coverage.

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

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

The description clearly states the verb 'semantic search INSIDE a fetched record' and specifies the resource as a fetched document. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining its unique role of saving context by returning only relevant passages.

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 the record is too big to cram into the prompt') and mentions a complementary tool (ask_pipeworx_grounded). However, it does not provide explicit when-not conditions or alternative tools, which prevents a higher score.

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

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

Annotations indicate idempotentHint true (safe to retry) and destructiveHint false. The description adds behavioral details: it creates a subscription (write operation), requires auth, returns an ID, and outlines constraints like phone verification and rate limits. No contradictions.

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

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

The description is well-structured and front-loaded with the core purpose and output. Though somewhat lengthy, every sentence adds value, covering types, delivery options, and 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?

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is extremely thorough, covering all subscription types, parameter details, delivery channels, and operational constraints like rate limits and webhook verification.

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 significantly enriches parameter understanding with real-world examples (e.g., ticker and items for sec_8k), type-specific formats, and delivery constraints (e.g., phone verification, webhook signing).

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription ID. It differentiates from sibling tools like list_subscriptions and unsubscribe by specifying the creation action.

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 (to set up monitoring), required authentication (Pipeworx OAuth), and provides detailed guidance on types and delivery channels. However, it lacks explicit 'when not to use' instructions, though context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns category-bucketed examples with tool+argument shapes, drawn from live catalog, aligning with annotations.

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

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

Description is information-rich, front-loads common queries, but is slightly lengthy. Every sentence adds value, though could be trimmed slightly.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers input, behavior, and usage completely. No missing critical information.

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

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

Parameter 'topic' is fully described with example values ('finance', 'pharma', 'betting') and note to omit for cross-category spread, adding value beyond the schema's enum list.

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 is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes, distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with/without topic. Does not explicitly mention when not to use, but usage 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?

Adds behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain via recent_alerts. No contradiction with annotations (destructiveHint=false, idempotentHint=true).

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 short sentences each serving a distinct purpose: action, constraint, behavioral effect. Every sentence earns its place with no redundancy.

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

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

For a simple cancellation tool with one parameter and no output schema, the description covers the core action, ownership rule, deactivation semantics, and links to related tool (recent_alerts). Complete.

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

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

Schema coverage is 100% and the schema description for 'id' is clear. The description reinforces 'by id' but does not add new 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?

Clearly states the action 'Cancel a subscription by id' with the verb 'cancel' and resource 'subscription'. Distinguishes from siblings by specifying ownership enforcement, making the purpose unambiguous.

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

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

Provides explicit context: ownership enforcement (you can only cancel your own subscriptions) and deactivation behavior. Does not explicitly name alternative tools like list_subscriptions or subscribe, but the guidance is clear enough.

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

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

Annotations already declare readOnly, openWorld, and idempotent, but the description adds critical behavioral context beyond that: the meaning of could_not_verify (a failed check, not evidence), 'unsupported' (no source coverage), the routing fallthrough for non-financial claims, and the inclusion of pipeworx:// citations. This is exactly the kind of non-obvious behavior an agent needs to know, and it does not contradict any annotation.

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

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

The description is long but well-structured: trigger examples, purpose, routing details, output summary, and an IMPORTANT note. Every section earns its place given the tool's complexity. The initial trigger list is slightly redundant, but the front-loading of purpose and the clear separation of the 'IMPORTANT for callers' caveat make it easy to parse.

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

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

Given there is no output schema, the description thoroughly covers the return values: verdict types, actual value with citation, reasoning, and the verification_error structure for could_not_verify. It also addresses edge cases like unsupported versus could_not_verify, which are essential for correct agent interpretation. The routing for financial vs. non-financial claims is fully specified, making the description complete for a complex tool.

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

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

Schema coverage is 100% (both claim and tolerance_pct have descriptions), so baseline is 3. The description adds tactical nuance by explaining the tolerance_pct semantics in context: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection' and that the default is capped at 5. This goes beyond the schema, which only says 'Max percent deviation still graded approximately_correct (0.5–50)'.

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: verifying natural-language claims. It opens with trigger phrases like 'fact check' and 'verify the claim that…', specifies the two routing paths (SEC EDGAR/XBRL for company-financial, grounded pipeline otherwise), and lists the verdict types returned. This strongly differentiates it from sibling tools like search_within or deep_research, and it even notes 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further describes when the structured financial fast path applies versus the generic grounded pipeline for all other factual claims, leaving no ambiguity. The note that it replaces 4–6 sequential calls also clarifies it as the consolidated alternative to composing other tools.

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