Utah Open Data

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: default model is Workers AI free, Anthropic requires BYO key with direct payment, returns per-model data including raw response. It doesn't contradict annotations and provides good transparency about costs and model selection.

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

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

The description is a single paragraph with no wasted words. It front-loads the main action, defaults, and return format, then adds use cases. Every sentence adds value; it's 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?

For a tool with 4 parameters, no output schema, and moderate complexity, the description is complete. It explains what each model returns (score, confidence, signals, raw_response) and a combined view. It covers default behavior, optional features, and use cases, leaving no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: for 'entity', it gives examples ('Pipeworx', 'OpenInvoice'), for 'models' it lists supported values and defaults, for '_apiKey' it explains passthrough to Anthropic, and for 'context' it clarifies disambiguation. This enriches the schema.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility 0-100 per model. It uses specific verbs ('Probe', 'score') and distinguishes from siblings by focusing on AI visibility, unlike similar tools like 'scan_competitor_ai_presence' which may have a different scope.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It tells when to use but doesn't explicitly state when not to or compare to sibling alternatives. However, the context is clear enough for an agent to decide.

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 carry the heavy safety/evaluation — readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false — and the description is consistent with them. It adds meaningful behavioral context: the tool routes to an index of thousands of sources, auto-fills arguments for sub-tools, and returns stable citation URIs. No description of possible fan-out latency or rate limits, but that is a minor gap given the 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?

The most actionable directive ('PREFER OVER WEB SEARCH' and 'START HERE') is front-loaded, and the body is organized into usage, scope, examples, and alternatives. It is on the long side and has some trailing/redundant gossip near the end, which keeps it short of a perfect 5.

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

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

Given the rich annotations and 100% schema coverage, the description goes beyond the minimum by covering the return contract (structured answer with citation URIs) even though there is no output schema. It covers the breadth of domains, example inputs, and the routing decision among sibling tools. What is mostly absent is a note about what happens when the query fouls all sources or is ambiguous.

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 itself defines the only parameter 'question' and all five aliases. The description adds value through example queries and the phrase signals that clarify what a good input looks like, lifting it slightly above the baseline 3. It does not contradict or obfuscate 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 states a specific behavior (routes the question, fills arguments, returns a structured answer with pipeworx:// citation URIs) and a concrete resource (5,596 tools across 1,465 verified sources). It also names exactly what the tool is not (web search, deep_research, ask_pipeworx_grounded) with clear domain boundaries, so an agent can differentiate it from siblings without opening their schemas.

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?

Usage is explicit: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks what is, look up, find, get the latest', 'START HERE for most questions'. It also provides explicit when-not guidance with named alternatives — 'use deep_research instead', 'use ask_pipeworx_grounded', 'use pipeworx_trending' — so the agent knows which sibling to pick in each case.

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

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

Beyond the annotations (read-only, open world, idempotent, non-destructive), the description adds meaningful behavioral context: no candidate is currently under test, so it currently matches ask_pipeworx exactly, while routing improvements may be live in the future. This explains how the tool's behavior can change over time.

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

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

The description is dense and front-loaded, with purpose, current state, and usage all covered in a short paragraph. The phrase 'Falls back to nothing' is slightly awkward and could confuse, but the overall structure is efficient and relevant.

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 router with one required natural-language parameter and no output schema, the description provides enough context: current behavior, experimental nature, and identical response shape to ask_pipeworx. An explicit pointer to the stable ask_pipeworx tool would strengthen it, but 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?

The input schema already documents question and its aliases with 100% described coverage, so the baseline is 3. The description contributes only 'same arguments' and instructs the agent to treat it like ask_pipeworx, which does not add parameter-specific 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 plainly identifies this as the beta version of ask_pipeworx: a universal router with the same 5,596 tools, arguments, and response shape. This clearly distinguishes it from the stable ask_pipeworx sibling and states what the tool is for.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and frames this as an experimental edge compared against the stable router. It could be stronger by explicitly stating when not to use it, but the 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?

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description goes further by explaining the refusal behavior, the exact success/refusal return shapes, the grounded-extraction constraint, and the extra cost. No contradiction with annotations.

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

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

The description is dense but well-structured: leading behavior and use context, then return shapes, then usage guidance and cost trade-off. Every sentence contributes value and is easy to scan.

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

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

Even with no output schema, the description compensates with the full success and refusal return objects. It explains the grounding mechanism, source count, failure reasons, and comparative cost. For a single-required-parameter tool, nothing essential is missing.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for 'question'. The description adds little about the input itself, but it doesn't need to because the schema already provides complete parameter semantics.

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

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

States a specific purpose: 'hallucination-resistant answer mode' that routes to the right tool and extracts answers using only tool results. Clearly distinguishes it from ask_pipeworx by the grounding/extraction behavior while saying it follows the same routing.

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

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

Explicitly says when to use it: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. Also gives the opposite context: 'prefer ask_pipeworx for casual lookups' because this mode costs one extra LLM call.

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

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

Annotations declare readOnlyHint=true, but description adds extensive behavioral details: fan-out to multiple data sources, resolver contract with match confidence, parent event extractor, news fallback handling, safety overrides for low confidence, closed markets, and illiquid spreads. Also explains resolution-rule risk. Goes far 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 very long and detailed. It uses section headings (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) which help structure, but includes many examples that could be condensed. Information dense but not concise; could be trimmed while retaining 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, description fully explains return object structure, including nested fields (result.market, result.analysis, result.evidence), important subfields (best_bid, edge_pp, market_match_confidence), and error states. Covers edge cases like low-confidence matches, closed markets, and parent events. Complete for a complex research 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 covers 100% of parameters with descriptions. Description adds context like default depth ('thorough'), clarifies market input accepts multiple formats, and explains include_raw behavior. Provides examples. Baseline 3, but extra value pushes to 4.

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

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

Description clearly states the tool researches Polymarket bets by pulling relevant Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by being a general research tool.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides detailed guidance on inspecting resolver contract for matching confidence, checking parent event for partitioned bets, and looking at tradeability warnings. Includes when tools short-circuits (low confidence, closed markets).

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds concrete data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting behavior. Could note potential data latency but still strong.

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 with information but well-structured: examples first, then usage guidance, then data sources, then sort order. It could be slightly more concise but no sentences are wasted.

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

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

Given no output schema, the description explains return format ('paired data + pipeworx:// citation URIs') and sorting. It covers essential behavior for a comparison tool replacing many lookups, though could mention pagination or size limits explicitly.

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 specifying that for companies, tickers or CIKs are expected, and for drugs, names. It also explains the underlying data pulled (revenue, net income, etc. for companies; adverse events for drugs).

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 with multiple verbs ('compare', 'rank', 'head to head') and specifies the resource (companies or drugs). It distinguishes from sibling tools like 'entity_profile' by emphasizing side-by-side comparison.

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

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

Explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and implies when not to use it (for single entity lookups, which go to entity_profile). Also quantifies efficiency ('Replaces 8–15 sequential lookups').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds limited behavioral context. It mentions the returned fields, which is helpful but not a behavioral disclosure beyond what annotations provide. 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 two sentences, concise and front-loaded with the core purpose. No extraneous words, every sentence adds value.

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

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

Given no output schema, the description adequately explains what the tool returns. It also provides a cross-reference to another tool (query/metadata) for using the resource_id. Minor gap: no mention of pagination behavior beyond the offset parameter, but that is covered in the schema. Overall complete for a search tool.

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

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

Schema coverage is 100%, with each parameter described. The description does not add new semantics beyond the schema; it only reiterates the keyword search function. Baseline score of 3 is appropriate as schema carries the burden.

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

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

The description clearly states the tool searches the Utah Open Data catalog by keyword, and lists the returned fields (resource_id, name, description, category, update date). It distinguishes itself from sibling tools like search_within or query by specifying the exact data source and return 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?

The description implies when to use (searching datasets by keyword) and hints at a follow-up action (pass resource_id to query/metadata), but it does not explicitly state when not to use it or compare with alternatives. For a tool with many siblings, more explicit guidance would improve this 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?

Beyond the readOnly/openWorld/idempotent annotations, the description explains parallel decomposition, findings packet fields (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), explicit gaps[] that are never invented, contradictions[] on deeper tiers, and semantic excerpting. These are operational behaviors an agent needs to trust and invoke the tool accurately.

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

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

The description is dense and front-loaded with prerequisites and usage routing, but it duplicates the depth parameter's schema documentation in prose, adding length without new information. No other sentence is wasted; a slightly stronger edit would remove that duplication.

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

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

With no output schema, the description compensates with the full output packet, latency expectations, authentication requirements, gap/contradiction behavior, and citation semantics. For a complex parallel research tool, this is sufficient to configure and invoke correctly.

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

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

The schema already describes both parameters thoroughly: question enum, natural language, broad/multi-part decomposition, and depth with quick/standard/thorough hop behavior plus paid status. The description repeats this depth verbatim, adding no substantial new parameter meaning. With 100% schema coverage, 3 is the appropriate 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?

Uses a specific verb + resource: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources... in ONE call' and explicitly states 'this is NOT open-web search.' Clearly distinguishes itself from ask_pipeworx by showing what it is not for ('For a single lookup use ask_pipeworx instead').

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

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

Provides explicit when-to-use and when-not conditions: 'ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx instead,' and 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx.' This gives complete routing guidance with an alternative named.

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 non-destructive, read-only, idempotent. Description adds valuable behavioral context: returns top-N relevant tools with full schemas ready to call, no second lookup needed.

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

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

Description is well-structured, starting with purpose, then usage examples, return value, and guidance. It is reasonably concise with no fluff, though slightly lengthy.

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

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

Despite no output schema, the description explains the output (names, descriptions, schemas) and that results are callable. Covers examples and usage context comprehensively.

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

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

Schema coverage is 100% and parameter descriptions are already detailed. The description does not add significant new semantics beyond what the schema provides, 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?

The description clearly states the tool finds tools by describing a data or task, lists many domains, and distinguishes itself from specialized siblings that target specific data sources.

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

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

Explicitly advises calling this tool 'FIRST when you have many tools available' and provides clear context about when to use it versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context like patent soft-failure ('soft-fails until reactivated') and return fields (up to 5 filings, sorted fundamentals). No contradiction.

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

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

The description is front-loaded with example queries but is relatively long (3-4 sentences). Every sentence provides useful information, but 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 the tool's complexity (multiple sources, soft-fail, fallbacks), the description thoroughly explains the return fields and behavior without an output schema. It covers all important aspects.

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

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

Schema coverage is 100%. The description adds meaning: explains that 'type' must be 'company' (only supported), 'value' must be ticker or zero-padded CIK, and why names aren't supported, referencing resolve_entity. This goes 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 the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific example queries and contrasts with chaining single-pack lookups, distinguishing it from siblings like search_within or query.

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 guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use: 'Names not supported — use resolve_entity first if you only have a name.'

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

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

Annotations provide destructiveHint and idempotentHint; description adds minimal beyond 'Delete'. No extra detail on side effects or error handling.

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

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

Two concise sentences, front-loaded with action, zero 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?

Complete for a simple delete tool: single required param, no output schema, description covers purpose and usage 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%; description adds no extra meaning beyond the schema's 'Memory key to delete'.

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 deletes a memory by key, using specific verb 'Delete' and resource 'memory by key'. 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?

Explicitly states when to use: stale context, done task, clear sensitive data. Mentions pairing with remember and recall, but does not specify when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint true and destructiveHint false. The description adds behavioral specifics (fetches page, extracts title/description/key links, emits markdown) but does not mention error handling or rate limits. It adds 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 concise (5 sentences) and well-structured: starts with the main action, describes the output, and lists use cases. Every sentence adds value 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 no output schema, the description describes the output as 'standard llms.txt markdown format' and 'single text blob'. It covers parameters and use cases. Missing details on error handling or invalid URLs, but for a straightforward tool, it is sufficiently complete.

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

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

Schema description coverage is 100%, with both parameters already documented clearly in the schema. The description's parameter details (e.g., 'Full URL' and 'Maximum number of link entries') closely mirror the schema, adding minimal new meaning. Baseline is 3 for high coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'Generate' and the resource (llms.txt for a URL). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on outputting a standard file 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?

The description provides explicit use cases (getting a client's site indexed, drafting llms.txt, auditing competitors) but does not explicitly state when not to use this tool or compare with alternatives. 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?

Annotations already indicate readOnly, idempotent, non-destructive. Description adds returned fields and parameter for inactive subscriptions, confirming safe behavior.

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

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

Two sentences efficiently convey purpose, returned fields, and usage guidance. No redundancy, front-loaded with key info.

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

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

Despite no output schema, description lists all returned fields. Parameter and usage are covered. Complete for a simple list 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% and description does not add extra meaning beyond the schema's parameter description. 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Differentiates from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use case: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly say when not to use, but gives clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context about what the tool returns (schema + metadata including columns, types, row count, etc.), going beyond the annotations to inform the agent about the output.

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 immediately states the tool's purpose, lists the output, and provides an example. No wasted words, and the key information is front-loaded.

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

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

Given the tool has only one parameter, no output schema, and the description fully explains what metadata is returned (columns, types, row count, category, last-updated), the description is complete enough for an agent to use this tool effectively.

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

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

Schema description coverage is 100%: the only parameter, resource_id, is already described in the input schema as 'Dataset id'. The description reinforces this with an example. Since the schema already provides meaning, the description adds minimal additional semantic value.

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 resource 'dataset's schema + metadata', listing the exact fields (columns, types, row count, category, last-updated) and includes a concrete example resource_id. This clearly distinguishes it from sibling tools like 'datasets' or 'query', as it's focused on metadata retrieval.

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

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

The description gives an example of usage (resource_id '7n5d-er3z') but does not explicitly state when to use this tool over alternatives or provide any context on prerequisites or exclusions. While the purpose is obvious, explicit guidelines are missing.

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 annotations only contain false hints, yet the description discloses significant behavioral traits: rate-limited to 5 per identifier per day, free and not counted against quota, anonymous filing returns a claim_token, and team reads digests daily. It also reveals the side-effect that filing influences roadmap. 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 adds essential information: purpose, usage triggers, exclusion, claim token mechanism, rate limit, and cost. It is front-loaded with the core purpose and usage. Slight deduction for being a dense wall of text without structural breaks, but it earns its length.

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

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

The description covers all critical context: what it does, when to use it, when not to, how the anonymous claim_token flow works, rate limits, cost/impact, and how to describe the issue (terms of Pipeworx tools/packs). No output schema exists, so the return token description is sufficient. Any agent reading this will know exactly how to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:...}) to read whether it was fixed'), and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This pushes it 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the verb (tell/send feedback). It also distinguishes itself from siblings with a specific exclusion: 'ONLY for tools served by this Pipeworx connection'.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This is a textbook example of usage instructions.

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 safety hints (readOnlyHint, idempotentHint). Description adds beyond annotations: states self-aggregating from CF analytics-engine, no PII, cached 5min-1h depending on window. 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?

Well-structured with front-loaded main function, then use cases, then additional context. Could be slightly more concise by trimming 'Self-aggregating signal' explanation, but still efficient.

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

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

For a simple read-only tool with one optional parameter, the description covers return content, use cases, data source, caching, and privacy. No gaps given the annotations provide the safety profile.

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

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

Schema covers the single 'window' parameter with enum and description. Description adds semantic meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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, top packs, and total call volume' over a window, using specific verbs and resource. It distinguishes itself from sibling tools by focusing on trending data rather than searching or querying.

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 (discovering hot data sources, confirming canonical tools, aligning use cases). Provides clear context for when to use this tool over other tools, though does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral detail: monotonicity checks, partition_sum logic, semantic anchor with Jaccard similarity, partition filter, fill check with realizable edge condition, and warnings about not trading when edge ≤ 0. All consistent with annotations.

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

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

The description is well-structured with clear sections for modes, semantic anchor, partition filter, fill check. It is dense with valuable information but somewhat lengthy. Every sentence serves a purpose; however, slight verbosity keeps it from a top score.

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

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

Given the tool's complexity (multiple modes, internal logic, fill check), the description covers all essential aspects: parameter usage, behavioral rules, output structure (opportunities[], partition_check, suggestions), and references sibling tool for custom sizing. No output schema exists, but response fields are explained adequately.

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

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

Schema coverage is 100% and both parameters have good descriptions. The description adds significant context: explains the role of event slugs vs topic seed questions, internal processing like Jaccard similarity (≥0.30), partition filter (placeholder fraction >20% returns null), and fill check details. This far exceeds baseline.

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

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

The description clearly identifies the tool as finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three invocation modes (no args, event, topic) each with a specific verb+resource purpose, setting it apart from siblings like polymarket_edges.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also mentions when to use sibling tool polymarket_fill_risk. However, it does not explicitly exclude alternatives or describe when not to use the 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, destructiveHint=false. The description goes far beyond by explaining caching (1h), segmentation into three model families, the presence of diagnostics, and detailed edge calculation logic including slippage and Kelly criteria.

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 detailed and well-structured, starting with purpose and then explaining model families, response structure, and knobs. However, it is quite long and contains technical specifics that may not be necessary for all users, reducing 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?

For a tool with no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates, diagnostics) and covers all relevant aspects such as caching, knobs, edge calculation, and model families. It is highly complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds context like tradeable-edge knobs and the rationale for slippage_pp (zero trading fees), but these are supplementary rather than essential for understanding 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 verb 'scan' and the resource 'Polymarket markets', and specifies the unique purpose: returning opportunities where Pipeworx data disagrees with market price. This distinguishes it from siblings like polymarket_arbitrage, which likely focus on pure arbitrage.

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 it's built for 'what should I bet on today' and mentions agents can discover opportunities without paging hundreds of markets, implying a daily exploration use case. It provides guidance on filters and knobs but does not directly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enriches this by detailing the source (daily polymarket_edges snapshots), the nature of the data (time-series, decay computed on |edge_pp_net|), and the behavior of snapshot gaps. 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 relatively long but well-structured, with separate sections for purpose, arguments, response fields, and limitations. Every sentence provides useful information, though some phrases (e.g., 'the latter is wide for a reason nobody is willing to take') add color but could be trimmed for conciseness.

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

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

Given the tool has no output schema and only two optional parameters, the description is remarkably complete. It fully explains the response structure (tracked, expired, snapshot_dates) and their fields, including first_seen, trend, decay_pp_per_day, lifespan_days, and snapshot dates. It also covers important limitations like the 60-day snapshot TTL and data granularity.

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 context for the 'window' parameter (specifying it's a snapshot family with default '1wk') and clarifies the 'days' parameter's clamping (2-30). This adds marginal value beyond the schema descriptions, which already explain defaults and ranges.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It directly addresses the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling tool 'polymarket_edges' by focusing on time-series analysis rather than current edges.

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

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

The description explicitly explains when to use the tool: to differentiate between fresh and old edges (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). It details the response structure and limitations (60-day TTL, daily closes). However, it does not provide explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context: walks the order-book ladder, returns verdict and detailed fields. No contradiction exists between description and 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 and well-structured with explicit sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, though it could be slightly trimmed without loss. Front-loads the core purpose effectively.

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

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

Despite lacking an output schema, the description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs). It covers edge cases like forced directional risk and maximum clean notional, making it comprehensive 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%, but the description adds significant meaning: explains side defaults for both modes, size_usd interpretation as spend vs target proceeds, and the auto detection for basket mode. It also clarifies value clamping (10-1,000,000).

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, with explicit differentiation between single-market and basket modes. It distinguishes this tool from siblings like polymarket_arbitrage by positioning it as a prerequisite check.

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

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

The description specifies exactly when to use this tool: before acting on polymarket_arbitrage signals or trades above ~$500. It explains why partial basket fills convert arbs into unhedged directional positions, providing explicit guidance on when not to use alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral context: output format (leg-by-leg prices, spread), safety fields with detailed conditions (matched_pairs=0 cases, temporal alignment), and counters for dropped comparisons. 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 appropriately sized given complexity. It front-loads the core purpose, then uses structured paragraphs with bolded terms and bullet-like enumeration for modes, response, and safety fields. Every sentence adds value; no redundancy.

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

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

For a complex tool with no output schema, the description comprehensively covers: input modes, response format (legs, spread, safety fields), when spreads are invalid (compatibility_warning conditions, temporal alignment), and counters for dropped comparisons. It is complete for an AI agent to understand invocation and interpretation.

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% (each property has a description). The description reinforces the schema by providing examples (e.g., 'KXFED-26OCT' for kalshi_event_ticker) and listing topic enum values, but does not add significant 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb 'compute spread' and the resource 'cross-venue pairs'. It distinguishes from siblings like polymarket_arbitrage which likely deals with different arbitrage types.

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

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

The description explains two modes (topic shortcuts vs explicit tickers) and when to use each. It explicitly warns that most pre-mapped topics return compatibility_warning, guiding users not to expect tradable spreads from the shortcut list. Safety fields like compatibility_warning and temporal_alignment provide clear when-not-to-use signals.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds that the tool returns JSON rows, uses SoQL clauses, and supports pagination (limit/offset). This adds value beyond annotations, but does not disclose potential rate limits or other edge-case behaviors.

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 primary action and resource. No filler, every phrase is necessary and informative. Excellent 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?

Despite 7 parameters and no output schema, the description covers the core use case: querying by resource_id with SoQL and pagination, and returns JSON. Examples in the schema fill any remaining gaps. Complete for its complexity level.

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

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

Schema coverage is 100% with descriptions per parameter. The description adds critical context: SoQL clauses must omit the leading '$', includes an example for each clause, and clarifies limit/offset pagination. This significantly enhances understanding beyond the raw 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 runs a Socrata SoQL query against a Utah Open Data dataset by resource_id, specifies the return format (JSON), and distinguishes from siblings like 'datasets' (likely lists datasets) and 'search_within' (different search), leaving no ambiguity.

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

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

The description explicitly says to use 'where/select/group/order' and 'limit/offset' with SoQL clauses, giving clear syntax guidance. It implicitly indicates that the tool is for querying data by resource_id, but does not explicitly contrast with sibling tools like 'datasets' or 'search_within', so it's slightly lacking for alternative exclusion.

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. The description adds context about scoping to an identifier and pairing with other tools, but does not significantly expand 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 three sentences, front-loading the core purpose, and every sentence adds value without redundancy. It is efficiently structured and easy to parse.

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

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

Given the simple tool with one optional parameter and no output schema, the description provides sufficient context for correct usage, including scope and usage patterns.

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

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

Schema coverage is 100% with description for the key parameter. The description adds additional meaning by explaining the key is a saved value and that omitting it lists all keys, complementing 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 retrieves saved values or lists all keys, using specific verbs 'retrieve' and 'list'. It distinguishes from siblings 'remember' and 'forget' by explaining the retrieval function.

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

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

The description explicitly states when to use the tool: to look up previously stored context without re-deriving. It also mentions pairing with 'remember' and 'forget'. However, it lacks explicit guidance on when not to use it or alternative tools.

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

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

Annotations indicate readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral details beyond annotations, such as the mark_read parameter affecting subsequent results (flagging events as read so next call shows only newer ones) and the return format including source and citation_uri.

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

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

The description is three sentences long, front-loaded with the main purpose. It efficiently packs in details about return fields, filtering, and the mark_read behavior without being verbose or redundant.

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

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

Given no output schema, the description adequately explains return values (source, citation_uri, raw event payload) and mentions an alternative feed. All optional parameters are addressed, and the tool's behavior with mark_read is clarified, making it complete for an agent to use correctly.

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

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

The input schema covers all 5 parameters with descriptions, but the tool description adds practical context: examples like 'sec_8k' for type, explanation of mark_read, and clarification that since is an ISO timestamp. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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 how to use the tool (filter by type, since, mark_read, unread_only) and mentions that polling works fine. It also provides an alternative endpoint for scripts/dashboards, offering usage context. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds transparency about the fan-out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO) and the fallback logic. It also describes the return format (structured changes, total_changes, citation URIs), adding 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 a single dense paragraph that conveys a lot of information without waste. It is front-loaded with example queries. While it could benefit from slight structural separation (e.g., listing sources), it remains concise and readable.

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

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

Despite no output schema, the description fully explains the return format (grouped changes, total_changes count, citation URIs). It covers all behavioral aspects: multiple sources, fallback, accepted inputs, and even a note about USPTO soft-fail. It is complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by clarifying that `value` can be a ticker or CIK, and suggests '30d' or '1m' for typical monitoring. It also explains the `since` shortcuts (7d, 30d, 3m, 1y) and ISO format, which goes beyond the schema descriptions.

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

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

The description opens with concrete example queries ('What's new with X' / 'latest on Y') and explicitly states it returns a change feed for a company in a time window. It clearly distinguishes from entity_profile, making the purpose unmistakable.

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

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

The description provides guidance on when to use this tool (e.g., 'Use entity_profile instead when you want the static profile') and explains fallback behavior (GDELT→GNews). It also explains accepted `since` formats. However, it could be more explicit about when not to use it.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. Description adds scoping by identifier, persistence differences (authenticated vs anonymous 24-hour). 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?

Four sentences, front-loaded with purpose, no redundancy. Each sentence adds unique 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 simple params, no output schema, and annotations, description covers usage, persistence, and pairing. Complete for the tool's complexity.

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

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

Schema covers both parameters fully. Description adds example keys but no additional syntax or constraints beyond schema. Meets baseline for high coverage.

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

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

The description clearly states the tool saves data for reuse, with specific examples like 'resolved ticker, target address, user preference'. It distinguishes from siblings recall and forget by mentioning them as paired tools.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and implies alternatives (recall, forget). Lacks explicit exclusions but provides clear context.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds valuable behavioral context: identifiers are labelled with their source, unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully if external services fail, and internal cascading lookups replace multiple manual steps. No contradiction with annotations.

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

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

The description is well-structured with examples first, then purpose, then detailed type-specific behavior. It is somewhat dense, especially the parenthetical on company identifiers, but every sentence contributes meaningful information. Slightly longer than ideal, yet organized.

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

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

With no output schema, the description fully compensates by explaining what each entity type returns (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), including source attribution and fallback behavior. It covers prerequisites, input formats, and edge cases comprehensively.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning with concrete examples (AAPL, 0000320193), explains type options, and clarifies special cases like ISIN resolving to the legal entity. This goes well beyond the schema's basic descriptions.

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

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

The description opens with concrete example queries and then explicitly states the tool's core function: resolving a user-spoken name to canonical/official identifiers. This specific verb+resource combination clearly distinguishes 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?

Strong 'when to use' guidance is provided: 'Use FIRST whenever you have a name but need an ID' along with multiple query examples and supported entity types. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks the explicit exclusion found in top-tier examples.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. No contradictions. Extra context about the composite operation is useful.

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: core action, mechanics, usage example. Every sentence earns its place; no extraneous words. Front-loaded with the most important 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?

Description covers purpose, mechanics, return values (ranked list with score, confidence, signal density), and use case. No output schema exists, so this is sufficient. Could mention error scenarios or limitations, but overall complete for a read-only, idempotent tool.

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

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

Schema coverage is 100%, with descriptions for all 4 parameters. The description reinforces key parameter semantics ('first entry treated as subject') and explains the internal use of ai_visibility_check, which adds context beyond the parameter descriptions.

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

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

The description starts with a clear verb-resource pair: 'Compare AI visibility across multiple entities side-by-side'. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (likely a different comparison type). It explains the process (probes, ranks, surfaces most/least recognized) with concrete examples.

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

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

The description explicitly states the use case: 'competitive AI-marketing audits' with a sample question. While it doesn't list alternatives or exclusion criteria, the sibling tool ai_visibility_check is implied for single-entity checks. The context is clear enough for typical use.

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

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

The description adds behavioral context beyond annotations, such as partial failures degrading gracefully and bundlephobia's first measurement taking 5-30 seconds. It does not contradict the readOnlyHint and idempotentHint annotations.

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

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

The description is a single informative paragraph that front-loads the main purpose and then details return fields and behavior. It is concise but could benefit from slight structuring 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's complexity and lack of output schema, the description thoroughly explains return fields (summary block, per-advisory, links, alternatives) and handles edge cases like partial failures. It is complete for effective usage.

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

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

With 100% schema coverage, the description adds value by clarifying that scoped packages are accepted and that version defaults to latest. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, combining deps.dev and bundlephobia data to answer 'should I add this package?' It distinguishes from sibling tools by focusing on npm dependency 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 explicitly specifies when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also notes the NPM-only limitation for v1 and directs to deps.dev for other ecosystems, providing clear context even without naming specific sibling tools.

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

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

Adds rich details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. No contradiction with annotations.

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

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

Efficiently structured with purpose first, then usage guidance, then technical details. Every sentence adds essential information; no wasted words.

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

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

Despite no output schema, description adequately explains outputs (passages, offsets, scores) and covers edge cases (truncation, flag). Complete for a tool of this complexity.

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

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

Schema coverage is 100% with good descriptions for all three parameters. Description adds minor context (e.g., truncation flag, examples) but does not significantly exceed schema detail, earning 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 states 'semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by focusing on already-fetched text, not general search, and mentions pairing with ask_pipeworx_grounded.

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

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

Explicitly advises use when record is too large for prompt and suggests pairing with ask_pipeworx_grounded. Does not list when-not-to-use alternatives but provides sufficient guidance for the intended scenario.

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 this is a write operation (readOnlyHint=false), idempotent, and not destructive. The description adds context beyond annotations: it explains the creation effect, required authentication, and limits (e.g., 10/day SMS cap). No contradiction with annotations.

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

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

The description is well-structured with clear sections for types and delivery channels, but it is somewhat lengthy. It front-loads the core purpose but includes many examples and details that, while useful, could be slightly 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?

The description thoroughly covers all subscription types, delivery options, prerequisites, and constraints. Despite no output schema, it mentions the return of a subscription id. It addresses likely user questions about authentication, phone verification, webhook signing, and rate limits.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains each enum value in 'type' with examples (e.g., sec_8k for 8-K filings with ticker and items) and details the 'params' and 'delivery' objects with constraints and syntax. This far exceeds the schema descriptions.

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

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

The description clearly states the tool creates a subscription to a live-data event stream and returns a subscription id. It specifies the resource (subscription) and action (create), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit guidance: requires Pipeworx OAuth account, and details delivery channels with constraints like phone verification and 10/day cap. It implicitly guides when to use this tool (to set up monitoring) but does not explicitly name alternatives for other use cases.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that it returns category-bucketed examples drawn from the live catalog and explains the return structure, providing valuable behavior 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 front-loaded with purpose and examples, and organized with parentheses for categories. It could be slightly more concise, but every sentence adds value.

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

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

Given no output schema, the description thoroughly explains what the tool returns (category-bucketed examples with tool/argument shape). Param coverage is full, and context signals are well-addressed.

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

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

Schema coverage is 100%, and the description adds details about the optional topic parameter, including example values and the effect of omitting it. This adds meaning beyond the schema's brief description.

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

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

The description clearly states it is the onboarding entry point, listing multiple natural language queries users might have. It specifies that it returns category-bucketed example questions with tool + argument shapes, distinguishing it from other tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and mentions learning how to call meta-tools. Though it doesn't list explicit alternatives, the context strongly implies when 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?

Adds significant behavioral details beyond annotations: row is deactivated (not deleted), historical events remain available via recent_alerts. Also clarifies ownership enforcement.

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

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

Two concise sentences, front-loaded with purpose, then key behavioral details. 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 required parameter and no output schema, the description covers ownership, side effects (deactivation vs deletion), and references related tools (subscribe, recent_alerts). Fully sufficient.

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

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

Schema coverage is 100% with a single parameter 'id' well-described in the schema. Description adds no additional parameter meaning beyond what the 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?

Clearly states 'Cancel a subscription by id.' Specifies verb and resource, and distinguishes from sibling tools like subscribe and list_subscriptions by noting ownership enforcement and deactivation behavior.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Does not explicitly list alternatives, but the context implies it should not be used for others' subscriptions.

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 the exact set of possible verdicts, distinguishes between 'could_not_verify' and 'unsupported', and warns that 'could_not_verify' must not be treated as evidence. It also explains routing behavior and the inclusion of citations/reasoning, all beyond what annotations (read-only, idempotent) convey.

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

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

The description is long but packed with useful information: trigger phrases, routing logic, verdicts, caveats, and replacement value. It is front-loaded with examples and structured clearly, though slightly verbose; a few clauses could be tightened without losing 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?

With no output schema, the description compensates by fully explaining return values (verdicts, actual value, citation, reasoning) and edge cases (could_not_verify vs. unsupported). It also covers the two routing paths, making it complete for an agent to understand the tool's full contract.

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

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

Schema description coverage is 100%, and the description itself does not add new parameter-level meaning beyond what the schema already provides. The schema already explains tolerance_pct overrides and the default behavior, so the description adds no additional parameter semantics.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with explicit trigger phrases and a specific verb-resource pairing ('verify the claim that…'). It distinguishes itself from sibling tools by focusing on fact-checking user claims and mentions the internal routing between SEC EDGAR and the grounded pipeline.

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 states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It clarifies the scope for company-financial claims vs. other claims, and explains that the tool replaces multiple sequential calls, giving clear context for choosing it over alternatives.

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