Texas Open Data

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds that Anthropic probing requires a BYO key and direct payment, and that scores are returned per model. It does not mention rate limits or result variability, but overall provides useful additional context beyond annotations.

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

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

The description is a single dense paragraph that front-loads the main action and then adds specific details. Every sentence adds value, with no wasted words. It is appropriately sized for the tool's complexity.

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

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

Given the tool has 4 parameters, no output schema, and returns complex per-model data, the description is fairly complete. It explains input, model options, and return structure ({score, confidence, signals, raw_response} + combined view). Missing details about aggregate scoring or confidence computation, but still adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the default model, purpose of _apiKey, and how context helps disambiguate. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and scores visibility (0-100) per model. It specifies default and optional models, and gives concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This distinguishes it from sibling tools like ask_pipeworx 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?

The description explains when to use the tool (for visibility checks) and how to configure models (default free Workers AI, optional Anthropic with BYO key). It does not explicitly state when NOT to use it or compare to alternatives, but the use cases are clearly defined.

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 assure readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about routing behavior, source count, and citation format (pipeworx:// URIs). However, it does not disclose any limitations like rate limits or result truncation, which would push to a 5.

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

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

The description is comprehensive but somewhat verbose. It front-loads the key message (prefer over web search) well, but the long list of examples and repeated 'START HERE' phrase could be tightened without losing clarity. Still, every sentence adds value.

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

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

Given the tool's complexity (5,564 underlying tools), lack of output schema, and multiple siblings, the description is nearly complete. It covers use cases, fallbacks, and source types. It could mention the return format beyond citation URIs (e.g., structured answer nature), but is functional as-is.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining what the 'question' parameter should contain (natural language fact queries) and provides varied examples across multiple domains, exceeding the schema's examples. The aliases are documented but this is already in 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: answering factual questions using 5,564 tools across 1,462 sources, with stable citation URIs. It distinguishes itself from siblings by explicitly listing what data domains it covers (SEC filings, FDA data, etc.) and contrasting with ask_pipeworx_grounded and deep_research for specific use cases.

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

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

Provides explicit guidance on when to use (prefer over web search, 'what is', 'look up', etc.) and when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (broad/multi-part questions). It even addresses breaking-news scenarios and free account tiers, leaving no ambiguity.

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

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

Annotations already mark the tool as readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by explaining the experimental nature, the fallback behavior (none—it's a full working router), and the current match to the stable version. However, it doesn't disclose additional behavioral traits like rate limits or latency implications for using the beta route, which would be useful context beyond what annotations already provide.

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

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

The description is a dense, front-loaded single paragraph with no wasted words. Every sentence adds unique context: the beta identity, the current state. Could benefit from slight restructuring (e.g., move the assertion about current matching earlier) but overall efficient.

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

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

Given the tool's complexity (universal router with 5,564 tools) and lack of an output schema, the description adequately covers purpose, current status, and usage intent. It doesn't explain return values or error modes, which would be helpful for a beta tool, but the tool's purpose and behavior are clear enough. The schema and annotations complement the description well.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description does not add any new parameter meaning beyond noting that question is the main argument and accepting aliases. Given high coverage, baseline 3 is appropriate—the description adds no extra semantic value for parameters.

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

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

The description clearly states this is a beta version of ask_pipeworx with the same universal routing capabilities (5,564 tools, same arguments, response shape). It explicitly distinguishes its purpose: testing candidate routing improvements, contrasting with the stable router. The verb 'ask' with 'pipeworx' plus the beta context is specific and informative.

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

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

The description provides explicit guidance on when to use this tool: 'when you want the newest routing'. It clarifies that results are compared against the stable router for merge decisions, and notes that currently it matches ask_pipeworx exactly since no candidate is active (with a specific date). No sibling tool addresses the same experimental routing context, and the description's instructions are precise about usage intent.

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?

Transparently discloses the tool's mechanism ('picks the right tool... fills arguments... fetches data... extracts using ONLY what the tool result contains'), return structure ({answer, evidence, confidence...}), refusal reasons, and cost ('costs one extra LLM call'). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, which align with the description's claims, so 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 well-structured and front-loaded, starting with purpose. It is slightly verbose (covers mechanism, return format, use cases), but every sentence adds value. Could be tightened slightly (e.g., removing duplicate alias list), but overall efficient for the complexity.

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

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

Given there is no output schema, the description compensates by detailing the return structure ({answer, evidence, etc.}) and failure modes. It is complete for the tool's complexity—covers purpose, usage, behavior, and costs. Lacks only explicit 'what to do on refusal' guidance, which is minor.

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

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

Parameter description coverage is 100% per context signals, so baseline is 3. The description adds value by explaining the effect: the parameter is a 'natural language question' accepted with multiple aliases (q, text, etc.). However, it doesn't detail advanced usage (e.g., formatting for optimal extraction), so a 4 is appropriate—adds meaning but could go further.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads.' It specifies the verb ('Extracts the answer'), the resource ('tool result'), and distinguishes itself from 'ask_pipeworx' by adding the extraction and refusal behavior, making it distinct among siblings.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists use cases (financial verdicts, legal claims, etc.). Also states when not to use: 'prefer ask_pipeworx for casual lookups' due to an extra LLM call cost. The distinction from 'ask_pipeworx' is clear and actionable.

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 extensive behavioral context beyond annotations, covering low-confidence resolution short-circuiting, closed market handling, wide-spread tradeability warnings, resolution-rule risk, and more. Annotations already indicate read-only and idempotent, and the description reinforces this while detailing edge cases.

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 with sections, but it is lengthy. While every section adds value, the overall length could be reduced without losing clarity. Front-loaded with the main purpose, but the verbosity lowers 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 complexity (3 params, no output schema), the description covers all necessary aspects: classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety checks, and resolution-rule risk. It fully compensates for the lack of an output schema by explaining what the response contains.

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

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

Schema coverage is 100% (all parameters have descriptions), so baseline is 3. The description adds extra meaning: explains possible input forms for 'market' (slug, URL, question text), elaborates on 'depth' with quick/thorough definitions, and describes when to set 'include_raw' to true. This lifts the score above baseline.

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

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

The description clearly states the verb ('Research a Polymarket bet') and the resource ('Pipeworx data'), with specific examples of inputs like market slug or URL. It distinguishes from sibling tools by mentioning Pipeworx data and focusing on Polymarket bets.

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

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

Explicit usage cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. While it doesn't explicitly state when not to use or compare to closely related siblings like 'polymarket_edges', the context is clear.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds how it handles fiscal years, sorts results, and returns citation URIs, going beyond annotations.

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

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

The description is dense and front-loaded with the purpose, but it is a single paragraph that could be slightly more structured. Every sentence adds value, though length could be trimmed.

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

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

Given no output schema, the description fully explains return values (paired data, citation URIs) and data sources for both types. It covers input constraints, behavior, and output, leaving no gaps.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds examples (e.g., tickers for company, names for drug) and notes on sorting and data sources, but the schema already provides the core 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 states the specific verb 'compare' and the resources 'companies' or 'drugs' with a clear scope of 2-5 entities in one parallel call. It also distinguishes from sequential lookups, making it highly precise.

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 triggers like 'Compare X and Y', 'rank these companies', and explicitly states preference over sequential lookups. No ambiguity about when to use this tool.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by specifying the catalog source and return format, which are not in annotations. No contradictions. For a read-only search tool, this is sufficient transparency.

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

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

Two sentences, front-loaded with action, no extraneous words. Every sentence serves a purpose: stating the function and summarizing output usage.

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 fields and the next step (pass resource_id to query/metadata). It could mention pagination behavior, but offset is defined in the schema. For a search tool with strong annotations, this is fairly complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description confirms the query is a keyword search and mentions defaults, but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches the Texas Open Data catalog by keyword, specifies returned fields (resource_id, name, description, category, update date), and explains how to use the result. This is a specific verb-resource pair that distinguishes it from siblings like 'query' or 'search_within'.

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 tells when to use the tool (keyword search for datasets) and hints at the next step (pass resource_id to query/metadata), but does not explicitly state when not to use it or compare to alternatives. However, the sibling list includes many unrelated tools, so the differentiation is implicit.

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

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

Annotations provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating non-destructive, consistent, read-only behavior. The description enhances this by detailing the decomposition into facets, parallel routing (5,564 tools), iterative hops (gap recovery for 'standard', lead chasing for 'thorough'), contradictions scan, semantic excerpting for large records, expected timing (15-90s), and citation behavior (stable pipeworx:// URIs that are fetchable). 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 comprehensive but somewhat lengthy (several paragraphs). It is well-structured with front-loaded account requirement and usage guidance, then key differentiators, then detailed behavior. Every sentence adds value, but some detail (e.g., exact number of data sources and tools) could be streamlined for clarity without losing critical information.

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

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

Given the tool's complexity (2 parameters, no output schema), the description fully covers input semantics, behavior (synchronous, parallel, iterative), return details (evidence, confidence, citation_uri, gaps, contradictions), timing, and when to use. It compensates for the lack of output schema by describing the findings packet structure. No gaps remain for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters ('question' and 'depth'). The description adds significant value by explaining the depth levels ('quick=3, standard=3 + gap recovery + contradictions, thorough=6 + leads + contradictions + gap recovery') and clarifying that broad/multi-part questions are acceptable. However, it does not provide usage examples or syntax guidance beyond the schema, keeping it at a 4 due to excellent but not exhaustive addition.

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

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

The description clearly states the tool performs 'grounded multi-source research' across structured data sources, decomposes questions into facets, runs parallel tool calls, and returns a findings packet. It distinguishes itself from siblings by specifically noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and breaking news.

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

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

Explicit guidance on when to use (broad/multi-part questions over structured data) and when not ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). Also provides alternatives (ask_pipeworx) and prerequisite (ACCOUNT REQUIRED).

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: it explains the return format (top-N tools with names, descriptions, full schemas, and curated examples) and states that results are 'ready to call directly.' Annotations already indicate read-only and idempotent, so the description supplements rather than contradicts.

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 reasonably concise given the breadth of information needed. It front-loads the core purpose and provides domain examples efficiently. Could be slightly tighter, but overall well-structured.

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

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

Despite no output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, schemas, curated examples) and when to use it. It covers all necessary context for a discovery tool, making it complete.

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

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

Schema coverage is 100% for 6 parameters, each with descriptions. The description mentions aliases (q, task, description, search) but this is already in the schema. No additional semantics are provided beyond what the schema already conveys. 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 'Find tools by describing the data or task' and enumerates many domains. It distinguishes itself from sibling tools (like query, search_within) by explicitly noting it should be called first to discover available tools. The purpose is specific and unambiguous.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the tool, though it does not explicitly list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: parallel fan-out, specific data returned, soft-fail for patents, and unsupported name input. No contradictions.

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

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

Description is somewhat long but well-structured: starts with example queries, then details return structure. Every sentence adds value. Could be slightly more concise, but the list format and clear sections are effective.

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

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

Given the complexity (multiple sources, multiple return fields) and no output schema, the description is very complete: specifies each data source, exact fields returned, sorting, URI format, and limitations. Provides sufficient detail for an agent to understand full behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds important context beyond schema: value must be ticker or zero-padded CIK (not name), type only supports 'company'. This clarifies usage and constraints.

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

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

The description clearly states the tool provides a holistic cross-source profile for US public companies, lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes from siblings by explicitly recommending it over chaining single-source lookups.

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

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

Explicitly states when to use (when user asks for a holistic view like 'tell me about X'), when not to (if only a name, use resolve_entity first), and lists limitations (patents API sunset, names not supported). Provides clear guidance on input format (ticker or CIK).

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 aligns with annotations; no contradictions. It adds context about clearing sensitive data and stale context, going beyond the annotations that declare destructiveHint=true.

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

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

Three sentences, front-loaded with the core action. Every sentence adds value: state action, give usage cases, suggest pairings. No fluff.

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

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

For a simple single-parameter deletion tool, the description covers purpose, usage, and pairing. No output schema is needed for a delete operation, and annotations handle safety. The tool is simple enough that 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 coverage is 100% with the 'key' parameter already described as 'Memory key to delete'. The description adds 'previously stored memory' but does not substantially enhance meaning beyond the schema.

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

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

The description clearly states the action ('delete'), the resource ('previously stored memory'), and the method ('by key'). It distinguishes from sibling tools like 'remember' and 'recall' by explicitly mentioning them in the usage guidelines.

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 scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall', giving clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches the page, extracts title/description/key links, emits standard markdown. It also notes output is a single text blob, which is helpful. 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 front-loaded purpose, followed by process, output format, and use cases. Every sentence adds value; no fluff or repetition.

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

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

Given the tool's simplicity (2 parameters, text output, no output schema), the description covers purpose, process, output, and usage scenarios comprehensively. An AI agent has enough context to select and invoke correctly.

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

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

Schema coverage is 100% (both parameters described). The description adds helpful examples: for url, 'e.g. "https://example.com" or a specific landing page'; for max_links, specifies default 25 and max 50. This adds value beyond the schema.

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

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

The description clearly states the verb (generate), resource (llms.txt file for any URL), and scope (production-ready, AI crawlers). It is specific but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence or ai_visibility_check. However, the verb+resource combination is sufficiently unique.

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

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

The description includes a 'Useful for' section listing three common scenarios (client's site, own project, competitor audit). This provides good contextual guidance, though it does not explicitly state when not to use the tool or mention 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds value by specifying the default scope (active) and the optional include_inactive parameter, as well as detailing the return fields. No contradictions.

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

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

Three sentences, each earning its place: first states action and output, second lists fields, third gives usage advice. No redundant words.

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

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

Given the single optional parameter and no output schema, the description covers purpose, return fields, and usage context. It omits mention of empty result behavior, but overall sufficiently complete for the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for include_inactive. The description reinforces the default behavior (active only) but does not explain the parameter's effect explicitly. 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 lists active subscriptions and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like subscribe and unsubscribe by mentioning 'review what you're monitoring' and 'find an id to cancel'.

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

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

The description explicitly advises using this tool to review subscriptions before adding more or to find an id to cancel. This provides clear decision context relative to siblings, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description complements these by detailing the returned metadata (columns, types, row count, category, last-updated), providing behavioral context beyond the annotations. No contradiction detected.

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 sentence that front-loads the purpose, includes key details and an example, and contains no extraneous words. Every word serves a purpose.

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

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

Given no output schema, the description lists the metadata fields returned (columns, types, row count, category, last-updated), which is helpful. It specifies the domain (Texas Open Data). It does not address error handling or authentication, but for a simple read-only metadata tool, this is sufficient.

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

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

With 100% schema coverage, the schema already defines resource_id as a string with an example. The description adds context that it's a 'Texas Open Data' dataset id and shows the example, but does not add substantial meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'a Texas Open Data dataset's schema + metadata', listing specific items like columns, types, row count, and includes an example resource_id. This distinguishes it from sibling tools like 'datasets' or 'query' which serve different purposes.

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

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

The description implies usage by providing an example resource_id, but does not explicitly state when to use this tool versus alternatives such as 'datasets' for listing datasets or 'query' for data retrieval. No exclusionary guidance is given.

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

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

Annotations are minimal (all hints false), but the description discloses crucial behaviors: rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow, and the fact that the team reads digests daily. This goes well beyond what annotations provide and sets proper expectations.

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

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

The description is long but front-loaded with the core purpose and all sentences contribute operational or scoping information. There is slight redundancy in the enumeration of feedback categories (broken/missing/needs to exist vs. bug/data_gap/praise), but overall it is efficient for the complexity of the tool.

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 and a nested context object, the description covers the full lifecycle: when to use, what to include, how to claim a token, how to follow up, rate limits, and scope exclusions. It leaves no critical operational gap for an agent invoking this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining the claim_token lifecycle in operational terms: filing without an account returns a token, and passing it back later reads the resolution status. This complements the schema's parameter descriptions, making the workflow clearer.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by explicitly limiting scope to 'tools served by this Pipeworx connection' and excluding tools from other MCP servers.

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 when' conditions for bugs, feature requests, data gaps, and praise, plus an explicit 'when not to use' rule (other MCP servers). It also instructs users on how to describe issues ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), giving clear decision guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h'). 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?

Concise, well-structured with bullet points. Front-loaded with what it returns, then use cases, then technical details. No redundant sentences.

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

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

Given the tool's simplicity (one optional parameter, no output schema), description covers return values, caching, and privacy. Could mention if there are limits on results, but overall adequate.

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

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

Schema coverage is 100% with enum and description for window parameter. Description adds usage guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), supplementing the schema.

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

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

Clearly states 'Returns the top tools, top packs, and total call volume over a recent window', specifying verb and resource. Distinct from siblings like discover_tools or ask_pipeworx.

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

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

Lists three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment), providing clear context. Doesn't explicitly state when not to use or name alternatives, but context is sufficient.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: monotonicity checks, partition sum with 3pp threshold, Jaccard similarity filter, placeholder filtering, and fill check against live order book. No contradictions.

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

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

Description is front-loaded with purpose but becomes lengthy with detailed sub-sections. While well-structured, it could be more concise by moving some internal details (e.g., Jaccard threshold) to a separate section. Still efficient for the complexity.

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

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

Comprehensive description covers all aspects: modes, return fields (opportunities, partition_check, fill_check), internal filters (semantic anchor, partition filter, fill check). No output schema but description fully explains expected outputs and edge cases.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining example slugs, accepting full URLs, and detailing the semantic meaning of each mode 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?

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Explicitly distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: no args for trending scan, event for specific market slug, topic for cross-event scanning. Also advises against trading when realizable_edge_pp <= 0, preventing misuse.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral detail: caching behavior (1h KV), internal models (FRED log-returns, GDELT), response structure with diagnostics, and edge calculation specifics. 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?

Very detailed and informative but overly long. Front-loads purpose but then lists detailed model families and response segments. Could be more concise 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?

Fully describes all aspects: purpose, models, output segments, diagnostics, caching, edge calculation, and parameter usage. No output schema, so description compensates fully. Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context beyond schema descriptions (e.g., explanation of kelly_fraction, tradeable-edge knobs, default values). Provides meaningful compensation for a complex set of parameters.

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

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

Clear verb 'scan' and resource 'Polymarket markets', with specific purpose to return opportunities where Pipeworx data disagrees with market price. Distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 target use-case 'what should I bet on today' and provides context for agents discovering opportunities. Provides guidance on knobs, but does not explicitly mention when 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?

The description exceeds the annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), limitations, and behavioral details (e.g., decay computed from daily closes of edge_pp_net). 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 relatively long but well-structured with a clear sentence, response format listing, and limits. Each part adds value, though some redundancy with schema exists.

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

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

Despite no output schema, the description thoroughly explains the response format including fields and meanings, compensating fully. For a complex tool, this 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 covers both parameters with descriptions. The description adds little beyond re-stating defaults and adding context about window family. With 100% schema coverage, 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 provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and decay. It distinguishes itself from siblings like polymarket_edges by focusing on time-series tracking.

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 the tool's purpose with a concrete example (fresh vs. 3-week-old edge) and mentions limits like TTL and snapshotting. It provides clear context but does not explicitly state when not to use or name 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent. The description adds extensive behavioral details: ladder walking, return fields for both modes, clamping of size_usd (10–1,000,000), and warnings about partial fills converting arb into directional positions. No contradictions.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and uses capitalization for emphasis. However, it is somewhat verbose, containing more detail than strictly necessary. Still, every sentence adds value, so it earns a high score.

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

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

With no output schema, the description fully enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like partial fills and thin legs, making the tool self-contained.

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

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

Schema coverage is 100%, but the description adds significant context: explains mutual exclusivity of market and event, side defaults per mode, auto-detection for basket side, and different interpretations of size_usd (spend vs proceeds vs settlement notional). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and describes two distinct modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its pre-trade validation role.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial basket fills cause unhedged directional risk). Provides clear context for when to use.

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

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

The description extensively details behavior beyond annotations: it explains the two modes, the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and the conditions under which spreads are reliable. It also warns that most pre-mapped topics currently return warnings. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. However, it is somewhat verbose; careful editing could reduce length without losing essential information. Still, each 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?

The description is remarkably complete given the tool's complexity. It covers all aspects: modes, input parameters, response fields, safety warnings, temporal alignment, and the rarity of real spreads. It compensates for the lack of an output schema by explaining the response structure in detail.

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

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

With 100% schema coverage, the description still adds significant value: it elaborates on the topic values (lists all 10 shortcuts), explains how explicit param overrides work, and provides examples. The description makes the parameter semantics richer than 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by specifying the cross-venue aspect and explicitly notes the two modes of operation (topic shortcuts and explicit tickers), leaving no ambiguity about what the tool does.

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

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

The description provides explicit guidance on when to use each mode: topic shortcuts for pre-mapped macros and explicit tickers for custom pairings. It also explains the compatibility_warning conditions (when spreads are not valid due to non-equivalent bet shapes or unrelated events) and the temporal_alignment check, helping the agent decide when the tool output is meaningful.

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, so the tool is safe for reads. The description adds that it returns matching rows as JSON and clarifies SoQL clause syntax (without leading $). This provides behavioral context beyond annotations without contradicting them.

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

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

The description is two sentences long, front-loads the core action, and provides essential details about input format and output. Every word earns its place with no redundancy.

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

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

For a query tool with 7 parameters all documented in the schema, the description sufficiently explains the purpose and output format. It could benefit from mentioning default limit behavior or error handling, but given the annotations and schema, it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the descriptions of each parameter exist. The description adds value by explaining how to use SoQL clauses without the '$' prefix and provides examples in the schema's examples field. This clarifies usage 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 Socrata SoQL queries against Texas Open Data datasets using a resource_id. It specifies the SoQL clauses and parameters, and distinguishes itself from sibling tools like 'datasets' which likely list datasets rather than query them.

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

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

The description does not provide guidance on when to use this tool versus sibling tools. No explicit when-to-use or when-not-to-use instructions are given, leaving the agent to infer use cases from the tool's name and context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: scoping to user identifier, and pairing with 'remember' and 'forget'. No contradictions.

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

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

Three sentences without fluff. Each sentence adds value: action, use cases, scoping and pairing. Highly efficient.

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

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

For a simple tool with one optional parameter, no output schema, the description is complete: retrieval, listing, scoping, and pairing. No missing information.

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

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

The schema covers the single optional parameter 'key' with description. The description adds behavioral meaning: omitting the key lists all keys, enriching the schema's 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 retrieves a value saved via 'remember' or lists all keys when the key argument is omitted. It distinguishes the tool from siblings like 'remember' and 'forget' by specifying its retrieval role.

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

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

The description explains when to use (look up context stored earlier) and provides examples (ticker, address, research notes). It implies alternatives by mentioning pairing with 'remember' and 'forget', but doesn't explicitly state when not to use it. Overall, the guidance is clear.

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

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

The description contradicts the annotations: annotation says readOnlyHint=true, but mark_read parameter modifies read state, implying a write side effect. This contradiction reduces transparency severely.

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

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

Five sentences pack all necessary information without wasted words. Each sentence adds unique value: purpose, payload contents, filtering, mark_read behavior, and alternative access.

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

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

No output schema, but description explains event contents. All parameters are documented with usage hints. Minor gap: interaction between mark_read and unread_only not explained, but manageable.

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

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

Schema coverage is 100%, and description adds meaningful context beyond schema descriptions (e.g., example type 'sec_8k', explanation of mark_read effect). Adds value without being redundant.

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 pulls fired events from the subscription feed, specifies what each event carries (source, citation_uri, payload), and distinguishes from sibling tools like list_subscriptions by focusing on alert events.

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 mentions polling works fine and provides an alternative URL for scripts/dashboards, giving usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Annotations already indicate readOnly, idempotent, not destructive. The description adds critical behavioral details: parallel call, source fan-out, fallback from GDELT to GNews, soft-fail for USPTO, return format with grouped changes and citation URIs. No contradictions.

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

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

The description is well-structured and concise (~150 words). It front-loads with intuitive query examples, then details sources, parameters, and return format. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains the return structure (structured changes[], total_changes, URIs). It covers all tool aspects: multiple sources, fallbacks, parameter behavior, and disambiguation from sibling. Complete for a complex tool.

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

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

Schema has 100% coverage, so baseline is 3. The description adds value by explaining `since` accepts ISO dates or relative shorthand (e.g., '7d', '3m'), gives typical usage '30d', and clarifies `value` can be ticker or CIK. This enhances understanding.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' using multiple sources. It gives specific query examples and distinguishes from sibling entity_profile. The verb 'change feed' and resources (SEC EDGAR, GDELT, USPTO) are precise.

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

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

The description provides explicit usage examples and directly tells when to use an alternative: 'Use entity_profile instead when you want the static profile.' It also explains the `since` parameter format and fallback behavior, guiding correct invocation.

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

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

Annotations indicate idempotentHint=true, not read-only, not destructive. Description adds persistence details (authenticated users get persistent, anonymous 24h) without contradicting annotations.

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

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

Concise, well-structured sentences front-loading the purpose. Every sentence adds value without redundancy.

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

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

Given the simple tool with no output schema, the description covers all necessary aspects: behavior, usage, persistence constraints, and pairing with sibling tools.

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

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

Schema covers 100% with descriptions for key and value. Description adds naming convention examples (e.g., 'subject_property') beyond schema, providing extra context.

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

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

The description clearly states the tool saves data for reuse across conversations, using specific verbs and resources. It distinguishes from sibling tools like recall and forget.

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

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

Explicitly states when to use (when discovering something worth carrying forward) and mentions alternatives (recall, forget) for retrieval and deletion.

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?

Even with strong annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: internal cascade through multiple endpoints, graceful degradation of LEI/FIGI enrichment when upstream services are unavailable, and the explicit reporting of unresolved identifiers under an `unresolved` field rather than silently omitting them. 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 extremely well-structured: it starts with user-facing query examples, states the core purpose, then breaks down supported types with rich detail. Every sentence adds value, including specific fallback behavior and roadmap references. No unnecessary repetition or filler.

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

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

Given the tool's complexity (multi-source lookup, multiple input formats, support for different entity types) and the absence of an output schema, the description covers all essential aspects: input types, output conventions (source-labelled identifiers, explicit unresolved list), graceful degradation, and even a citation format for drug lookups. It is fully sufficient for an agent to use the tool correctly.

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

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

Although the schema already has 100% coverage, the description enriches the parameter semantics significantly: it provides concrete input examples (AAPL, 0000320193, ozempic), explains the ISIN-to-LEI mapping for non-US issuers, and contrasts company vs. drug behavior. This goes far beyond the schema's basic parameter documentation.

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

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

The description gives a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from sibling tools by adding 'Use FIRST whenever you have a name but need an ID' and enumerating supported entity types (company, drug) with specific 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?

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID' and lists example queries that trigger the tool. It also explains when alternatives would be unnecessary (if you already have an ID) and notes that it replaces 2-3 manual lookups, giving the agent a clear decision framework.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds that it probes entities with ai_visibility_check and returns a ranked list with scores, confidence, and signal density, providing useful behavioral context beyond annotations.

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

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

Three tight sentences front-loaded with the main purpose. Every sentence contributes unique information with no redundancy or fluff.

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

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

Given 4 parameters (1 required), 100% schema coverage, and no output schema, the description sufficiently explains the tool's operation and output format. It could mention the return type (ranked list) but does so indirectly.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining that the first entity is treated as the 'subject' and the rest as competitors, and clarifies the role of optional parameters (models, _apiKey, context). This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource (AI visibility across entities). It differentiates from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and ranking.

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

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

The description explicitly states the tool is 'useful for competitive AI-marketing audits' and gives a concrete example. While it doesn't list when not to use it or name alternatives, the context and sibling list make the use case clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral context: graceful degradation for partial failures, bundlephobia's initial 5-30s latency, and the sources_failed list. 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 slightly long but every sentence adds distinct value. It is front-loaded with the core purpose and return structure. Could be tightened slightly, but overall 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?

Despite no output schema, the description thoroughly details the return structure (summary block, per-advisory detail, links, recent alternative versions) and covers edge cases like partial failures and timing. This provides complete context for the tool's 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?

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying scoped package syntax ('@types/node') and default behavior when version is omitted. While the schema is already clear, the examples enhance usability.

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 succinctly defines the tool as a composite check for npm packages, fanning out to deps.dev and bundlephobia. It clearly states the verb ('check') and distinguishes from siblings by specifying the npm ecosystem and composite nature.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and provides guidance for other ecosystems (PyPI/Maven/Cargo/Go) by directing to alternative tools. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, but the description adds rich behavioral context: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char windows, caps at 200K chars with truncation flag. 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 a single paragraph that efficiently conveys purpose, usage, and technical details. Every sentence is informative with no redundancy. Front-loaded with the core verb and noun.

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

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

Given the complexity (semantic search, parameters, truncation, and no output schema), the description fully covers what the tool does, when to use it, how it works internally, and limitations. An agent can confidently select and invoke this tool.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the purpose of 'text' (document text), providing example queries for 'query', and specifying the range and default for 'limit'. This goes beyond the schema definitions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', specifying the verb (search), resource (a fetched record), and scope (inside the text). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and addressing the problem of large documents.

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 'Use when the record is too big to cram into the prompt' and provides an alternative tool (ask_pipeworx_grounded) for grounding over relevant passages. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate this is a mutation (readOnlyHint=false) that is idempotent and non-destructive. The description adds transparency by stating it returns the new subscription id and detailing delivery channel behaviors (e.g., webhook signing, auto-disable after 10 failures). No contradictions with annotations.

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

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

The description is well-structured, starting with the core purpose, then requirements, then supported types, and finally delivery channels. Every sentence adds value, though it could be slightly more concise without losing essential details.

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

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

Given the moderate complexity (3 parameters, nested objects, no output schema), the description is exceptionally complete. It covers prerequisites, return value, type-specific params, delivery behaviors, and constraints like phone verification 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?

With 100% schema coverage already providing parameter definitions, the description significantly enriches meaning by giving concrete examples for each 'type' and 'params' combination, and explaining constraints for delivery fields (e.g., phone verification, SMS cap). This goes well 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 explicitly states the tool creates a proactive monitoring subscription and returns the subscription id. It clearly distinguishes this from sibling tools like 'unsubscribe', 'list_subscriptions', and 'recent_alerts'.

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

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

The description provides clear context for when to use the tool, including prerequisites (Pipeworx OAuth account), specific event types with examples, and delivery channel options. It does not explicitly state when not to use it, but the sibling list and the detailed use cases make the appropriate scenarios evident.

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 safe, non-destructive behavior. Description adds that it returns categorized example questions with tool/argument shapes, which is useful context beyond annotations.

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

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

Front-loaded with key aliases and purpose. Each sentence adds value, though slightly verbose. Could tighten but still effective.

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

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

Given no output schema, the description explains return format (category-bucketed examples) and use case thoroughly. Complete for onboarding tool with one optional parameter.

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

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

Schema coverage is 100% for the single parameter. Description adds specific example values and explains the effect of omitting/using the topic parameter, enriching meaning beyond the schema.

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

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

The description clearly states the tool returns example questions for onboarding, distinguishing it from siblings like ask_pipeworx or compare_entities. It uses specific verbs and resources.

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 using this tool first when the agent doesn't know what Pipeworx can do. Includes optional topic parameter for focus. Lacks explicit when-not-to-use advice, but context is clear.

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

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

The description discloses that the row is deactivated not deleted, and historical events remain via 'recent_alerts', which adds value beyond annotations (idempotentHint, destructiveHint). 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?

Two sentences, no filler, front-loaded with the core action, very 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 tool with one parameter and good annotations, the description covers purpose, usage constraint, behavioral outcome, and a relevant sibling tool, making it complete.

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

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

Schema coverage is 100%, so the description adds no extra meaning beyond the schema. Baseline of 3 is appropriate.

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

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

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

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior, which guides when to use this tool. Does not explicitly contrast with other tools but the context is clear.

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

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

Annotations already indicate a safe read-only, idempotent operation, so the description adds valuable context: it details the SEC EDGAR/XBRL path for financial claims, the grounded pipeline for others, and importantly distinguishes could_not_verify (pipeline failure, not evidence) from unsupported (no source covers it). This goes well beyond annotations and prevents misinterpretation of results.

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 trigger phrases and provides a well-organized flow: usage, processing paths, return values, caveats. It is somewhat long but dense with necessary information for a complex tool. Every major sentence contributes value; a slight trim 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?

No output schema exists, so the description fully explains return semantics: enumerated verdicts, grounded actual value with citation, reasoning, and the critical error-handling distinction between could_not_verify and unsupported. It also explains the tool's efficiency benefit. For a tool with this complexity, the description is remarkably 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 provides 100% coverage for both parameters (claim and tolerance_pct) with clear descriptions. The tool description does not add parameter-specific meaning; it only indirectly references tolerance by mentioning 'exact percent-delta math'. With full schema coverage, 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 performs natural-language claim verification against authoritative sources, with specific verbs like 'validate', 'fact check', and 'verify'. It distinguishes itself from sibling research/query tools by framing the purpose as checking factual correctness and noting it replaces 4–6 sequential calls, which uniquely positions its role.

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 it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the two processing paths (SEC EDGAR fast path vs. grounded pipeline) and notes unsupported means no source exists. It lacks explicit when-not guidance or named alternatives, but the context is strong.

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