Medical Codes

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: probes LLMs, returns per-model data, mentions direct payment for Anthropic. Adds value beyond annotations without contradiction.

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

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

Two sentences, front-loaded with purpose, then details. Every sentence earns its place 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?

Without output schema, description compensates by outlining return fields. Covers all 4 parameters, required fields, and usage scenarios. Slightly missing explicit list of supported models beyond the two mentioned, but schema allows extensibility.

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 100%, baseline 3. Description adds meaning: explains default model, _apiKey passed directly, context disambiguates, and outlines return structure (score, confidence, signals, raw_response), which is not in schema.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility. It uses specific verbs and resources ('Probe', 'score visibility') and distinguishes from siblings by its unique focus on AI visibility audits.

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?

Explains usage contexts (AI-marketing audits, pre-launch checks, competitive monitoring) and provides guidance on default vs paid model. Lacks explicit when-not or alternative tools, but context signals show many siblings; the description effectively differentiates itself.

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

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

The annotations already mark this as read-only and non-destructive, and the description adds context about routing across thousands of sources, returning 'structured answer with stable pipeworx:// citation URIs', and being 'one fast call' that 'works on every tier'. This goes beyond the annotation hints to clarify what the agent can expect from the response.

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 every sentence provides actionable information: purpose, scope, examples, alternatives, and caveats. It is front-loaded with the critical directive 'PREFER OVER WEB SEARCH' and uses short clauses to maintain readability.

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

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

Given the tool's complexity as a universal query router with no output schema, the description covers the return format (structured answer with citations), the breadth of data sources, and the relationship to sibling tools. It is complete enough for an agent to decide when to invoke it and what to expect.

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

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

The input schema covers all parameters with complete descriptions, including aliases for the required 'question' field, so the description doesn't need to add parameter detail. The description confirms the parameter accepts natural language questions and examples, but the schema already provides this.

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

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

The description opens with 'PREFER OVER WEB SEARCH for questions about current or historical data' and explicitly states the tool 'Routes the question to the right one of 5,529 tools across 1455 verified sources', clearly identifying it as a query tool for authoritative data. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit usage guidance: 'START HERE for most questions — this is the default entry point' and specifies when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for broad/multi-part... use deep_research'). It also provides concrete examples and tells users to prefer it over web search.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: the tool is experimental, may change behavior when a candidate routing improvement is live, currently matches ask_pipeworx exactly with no active candidate, and is a full working router with no fallback. This exceeds what annotations alone 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 front-loaded with 'Beta version of ask_pipeworx' and is reasonably concise. Each sentence adds value: identity, current state, usage, comparison purpose, and fallback behavior. Slightly wordy but 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?

The description covers identity, current state, relationship to the stable router, why to use it, how results are evaluated, and fallback behavior. It even notes the response shape and tool count, making it complete for a tool with no output schema and rich annotations.

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

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

Schema coverage is 100% and all six parameters are aliases for 'question' with full descriptions. The description says 'same arguments' as ask_pipeworx but adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a beta version of ask_pipeworx that routes to the same 5,529 tools with identical arguments and response shape, positioning it as the experimental variant. It distinguishes itself from siblings like ask_pipeworx by emphasizing candidate routing improvements and live testing status.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear when-to-use signal. It names ask_pipeworx as the stable alternative and notes result comparison, though it does not explicitly state 'avoid if stability is critical.'

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

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

Beyond the readOnlyHint and other annotations, the description discloses critical behaviors: the extraction is limited to tool results, refusal is explicit with specific reason codes, and it costs an extra LLM call. This adds substantial context that annotations alone don't 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 compact yet dense, covering purpose, mechanism, return format, usage guidance, and cost in two short paragraphs. Every sentence earns its place, with the most important info front-loaded.

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

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

The tool's complex behavior (routing across thousands of tools, guaranteed extraction, refusal protocol) is fully described. The return format and refusal reason codes are explicitly stated, which is especially valuable given the absence of an output schema. It also contextualizes the tool against its sibling.

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 fully documents all six parameters as aliases for question, so the description adds no parameter-specific detail. Since schema coverage is 100%, the 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 identifies the tool as a 'hallucination-resistant answer mode' and explains its grounded extraction mechanism that uses only the tool result. It distinguishes itself from sibling ask_pipeworx by the specific return format and refusal behavior, making the purpose unmistakable.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on...') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including a cost trade-off. This is a model of clear 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. The description adds extensive behavioral context: low-confidence resolution short-circuits, closed markets return status, wide-spread markets carry tradeability notes, and resolution-rule risk parsing. It also explains safety measures like suppressing analysis on phantom matches. This goes well beyond annotations.

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

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

The description is very long and detailed, covering many categories and response shapes. While every sentence likely adds value, it could be more structured and concise. Some information is repeated (e.g., low-confidence match handling appears multiple times). A score of 3 reflects adequate but not optimal conciseness.

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

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

Given the tool's complexity (multiple classifiers, fan-out to various data sources, error handling, and no output schema), the description is highly complete. It covers examples, response shapes, resolver contract, parent_event extraction, news fields, safety, and resolution-rule risk. The agent has all necessary context to use the tool correctly.

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

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

Schema coverage is 100% with all three parameters described. The description adds value by providing examples for market (slug, URL, question text), explaining depth options (quick vs thorough), and clarifying include_raw usage (summarized vs full payloads). This adds meaning beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research, pull data). Examples of usage like 'should I bet on X' further clarify. It distinguishes from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on research and data gathering.

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

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

The description explicitly says 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z' which gives clear context. It does not explicitly state when not to use it or alternatives, but the provided use cases are helpful. A score of 4 reflects clear context without exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. Description adds context about off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradictions, but could add rate limits.

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

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

Description is detailed yet focused. Each sentence adds value. Could be slightly more concise but all information is relevant and well-structured.

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

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

No output schema, but description explains returned data fields (revenue, net income, cash, debt; adverse events, approvals, trials) and citation URIs. Adequate for agent to understand behavior.

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

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

Schema has 100% coverage with descriptions. Description adds practical guidance: for values parameter, explains tickers/CIKs for company and names for drug, plus min/max items. Adds value beyond schema.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs. It provides specific trigger phrases and differentiates from sibling tools like entity_profile which handles single 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?

Explicitly states to prefer this over sequential single-pack lookups when comparing entities. It also distinguishes between company and drug types, giving clear use cases.

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

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

Beyond the annotations, the description discloses a wealth of behavioral details: the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), the conditional presence of citation_uri, semantic excerpting of large records, depth-specific iteration behavior, and latency expectations (15-60s, up to ~90s for thorough). All of this is consistent with the readOnly/openWorld/idempotent 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 information-dense and well-structured: account prerequisite first, then core functionality, tool comparisons, depth behavior, output packet details, and performance expectations. Every sentence adds useful context, but it is more verbose than strictly necessary, so a perfect 5 is not warranted.

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 that there is no output schema, the description fully compensates by explaining the return packet fields, the citation_uri fetchability condition, gaps[] and contradictions[] semantics, performance, and prerequisites. There are no critical unknowns remaining for an agent to decide when and how to 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%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it elaborates depth levels with practical consequences ('standard re-angles unanswered facets', 'thorough chases leads'), and clarifies that the question parameter accepts broad/multi-part natural language. This is a moderate improvement over 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 identifies the tool as 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, providing a specific verb+resource. It further distinguishes itself from siblings by explicitly stating 'this is NOT open-web search' and contrasting with 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?

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directs users to ask_pipeworx for single lookups and breaking current-news topics. It also handles the not-signed-in case by recommending ask_pipeworx as an alternative.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context about the output format (returns schemas with curated examples, ready to call directly). 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 front-loaded with the core purpose and organized into two clear parts: what it does and when to use it. A few sentences could be tightened, 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?

Despite no output schema, the description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas.' This is complete for the tool's role as a discovery mechanism.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds value by clarifying that multiple aliases (task, q, description, search) map to the same query parameter, and provides usage examples.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many specific domains. It distinguishes itself from sibling tools by being a meta-tool for discovery, which is unique among the sibling list.

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

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

The description explicitly advises '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 versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant value by detailing the parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and returning specific fields. It also discloses the patents API sunset status, which is critical behavioral information not captured by annotations.

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

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

The description is dense but well-structured: example queries at the start, usage advice, then detailed return fields. Every sentence adds value. It could be slightly trimmed (e.g., the patents sunset note could be shorter), but overall it is efficient and front-loaded. It earns a 4 for being informative yet not overly verbose.

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 data sources, fallback mechanisms) and the absence of an output schema, the description thoroughly covers what the tool returns: CIK, company_name, recent_filings with URIs, fundamentals (latest 10-K values sorted), patents (with sunset warning), news (GDELT→GNews fallback), and LEI. It also mentions the parallel call nature, leaving no major gaps for an AI agent to understand the tool's capabilities.

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 type (enum: company) and value (string) are described. The description adds meaning beyond the schema by clarifying that value can be a ticker or zero-padded CIK, and that names are not supported. It also implies that type is currently fixed to 'company', which is consistent with the schema. The description adds value but the schema already does most of the work.

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

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

The description opens with example queries like 'Tell me about X' and 'research Acme', then states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It explicitly lists return fields (CIK, filings, fundamentals, patents, news, LEI), making the purpose very clear. It also distinguishes from sibling tool resolve_entity by noting that names are not supported.

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 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view' and provides clear guidance: pass ticker or CIK, not names. It directs users to resolve_entity if they only have a name, and notes the patents soft-fail until May 2025. This provides excellent 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 already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, but no additional behavioral details beyond deletion. Slight value added.

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, then usage guidance. 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?

Simple tool with one parameter and no output schema. Description, annotations, and schema provide complete guidance 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 'Memory key to delete' description. The tool description does not add further meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description uses specific verb 'delete' and resource 'memory by key', clearly defining the tool's function. It distinguishes from siblings by referencing 'remember' and 'recall' as complementary tools.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names related tools for pairing.

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?

Fully aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds detail about fetching, extracting, and emitting format. No contradictions; description enhances understanding of what the tool does internally.

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 two sentences plus bullet list. Front-loaded with main purpose. No unnecessary words; every sentence adds value.

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

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

Given the simple tool (two params, no output schema), the description covers purpose, usage, behavior, and output format completely. Annotations cover safety and idempotence.

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 repeats schema descriptions without adding new semantic info beyond examples and default/max for max_links.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb and resource. It distinguishes from siblings like ai_visibility_check by focusing on generation rather than checking visibility.

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 three concrete use cases (client indexing, personal project, competitor audit). No explicit when-not-to-use or comparison with alternatives, but the use cases are clear and complete enough.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds return field names and default active filtering, which is helpful context beyond annotations.

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

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

Two sentences, purpose first, no superfluous words.

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

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

No output schema but description lists return fields. Covers purpose, usage, and parameters adequately. Minor gap: no mention of pagination or ordering, but tool is simple.

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 single parameter with description. Description does not explicitly explain the parameter but implies its effect via 'active subscriptions.' High schema coverage (100%) keeps baseline at 3.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, distinguishes from siblings like subscribe/unsubscribe, and lists returned fields.

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: 'to review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use or alternative tools.

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

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

The description reveals behavioral traits far beyond the annotations: rate-limiting ('Rate-limited to 5 per identifier per day'), the return of a claim_token when filing without an account, and how to use that token later to read resolution status. It also mentions that the team reads digests daily and signals affect the roadmap, and that the tool is free. Annotations are all false but uninformative; the description carries the full burden and excels.

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

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

The description is long but every sentence is purposeful: scope, use cases, exclusions, claim_token mechanics, rate limits, and cost. It is front-loaded with the core purpose and then provides operational details. While not as minimal as a two-sentence example, the density is justified by the tool's nuanced behavior.

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 what the tool returns (a claim_token) and how to use it later. It covers the full feedback lifecycle: reporting, following up, and resolution. This is a complete picture for an agent to invoke the tool effectively in various scenarios.

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 four parameters have descriptions), so a baseline of 3 applies. The description adds value beyond the schema: it clarifies the claim_token usage pattern ('pass it back later... to read whether it was fixed'), emphasizes describing issues in terms of Pipeworx tools/packs rather than pasting user prompts, and relates the 'type' values to concrete scenarios. This pushes it to a 4.

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

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

The description opens with a clear directive: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This specifies the action (tell), the resource (Pipeworx team), and the scope of feedback (broken, missing, or needed). It also distinguishes this tool from sibling tools by stating it is ONLY for tools served by this Pipeworx connection, not for 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?

Explicitly defines when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is a textbook example of 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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral context: self-aggregating signal derived from CF analytics-engine, no PII, cached 5min-1h depending on window. 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?

Three short paragraphs, front-loaded with main result. Each sentence is informative and avoids fluff. Could be slightly more concise by merging some points, 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?

No output schema, but description explains return content (top tools, top packs, total call volume) and provides caching info. Lacks explicit return format structure (e.g., whether counts or just names), but sufficient for typical use.

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

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

Schema covers 100% of parameters with description, and the description adds interpretative guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This gives semantic meaning beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with a specific resource ('what other AI agents are calling on Pipeworx right now'). It uses a specific verb 'Returns' and distinguishes from siblings by focusing on trending aggregated data rather than individual search or discovery.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, seeing alignment). Lacks explicit when-not-to-use or alternative tool names, but provides clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral detail: internal checks (semantic anchor with Jaccard similarity, partition filter, fill check against CLOB depth), response structure, and edge cases (skipped_low_similarity, placeholders_filtered). 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 detailed and well-structured, front-loading the core purpose and then expanding on modes and internal logic. Every sentence adds value, but the length is somewhat high; some internal details (e.g., Jaccard similarity threshold, placeholder fraction) could be streamlined without loss of clarity. However, for a complex tool, this is acceptable.

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: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}.' It covers all three modes, internal checks, and edge cases. The tool is non-trivial, and the description provides complete contextual coverage.

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 greatly enriches meaning: explains the difference between event and topic modes, provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and notes that full Polymarket URLs are accepted for event. This goes well 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three distinct modes (no args, event, topic) and differentiates from siblings by focusing on arbitrage detection, as seen in sibling list with related but distinct 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?

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning).' It explains when not to trade (realizable_edge_pp ≤ 0) and points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This covers when, when-not, and alternatives.

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

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

The description adds significant value beyond annotations, explaining caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), model families, and how constraints like partition filtering work. It does not contradict annotations.

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

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

The description is quite verbose with multiple paragraphs, but it is well-structured with numbered segments and front-loaded purpose. Although every sentence adds value, it could be more concise without losing clarity.

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

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

Given the tool's complexity (9 params, no output schema, no required params), the description explains response structure, edge cases (Fed bets excluded), and diagnostics. However, explicit details on return format are somewhat lacking without an output schema.

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

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

With 100% schema description coverage, the description goes further by explaining how parameters like min_liquidity and max_spread_pp function as tradeability knobs, providing examples (e.g., 'Set to 5000 to drop thin-book opportunities'). For min_partition_leg_kelly, it clarifies why min_kelly does not apply.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use-case of 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 (daily betting opportunity discovery) and details tradeable-edge knobs and filters. However, it does not explicitly state when not to use it or compare directly to sibling tools.

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

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

The description extensively adds behavioral details beyond annotations: it explains the response structure (tracked, expired, snapshot_dates), the meaning of trend and decay_pp_per_day, signed values, and data gaps. This aligns with the readOnlyHint and other annotations without contradiction.

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

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

The description is well-structured with clear sections (purpose, args, response, limits) and front-loads the key question. While verbose, each sentence contributes value; minor redundancy could be trimmed.

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

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

Given the complexity and lack of output schema, the description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]), edge cases (data gaps, decay interpretation), and limitations. It is complete for agent 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% and both parameters are adequately described in the schema. The description adds minimal additional context (defaults and snapshot family concept). Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' from polymarket_edges snapshots, answering specific questions about edge duration and shrinkage. It distinguishes from sibling tool 'polymarket_edges' by focusing on temporal analysis.

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

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

The description includes context on when to use the tool (comparing fresh vs. old edges) and mentions limits like the 60-day TTL. However, it does not explicitly state when not to use it or provide direct alternatives, though siblings are available.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only check. The description adds valuable behavioral details: it walks the ladder, returns specific metrics (top_of_book, vwap, slippage), and warns about unconverted arb 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 comprehensive but somewhat lengthy. It is well-structured with bold headers ('SINGLE-MARKET', 'BASKET') and a clear usage recommendation paragraph. While every sentence earns its place, the length slightly impacts conciseness. Front-loading of purpose and usage is 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?

There is no output schema, but the description lists all expected return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases like thin books and partial fills, making the tool fully understandable.

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 parameters are well-defined structurally. The description goes beyond the schema by explaining the interplay between `market` and `event` modes, detailing defaults for `side` and `size_usd`, and clarifying how `size_usd` is interpreted differently in single vs basket modes. This adds significant semantic value beyond the bare schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth, explicitly distinguishing between single-market and basket modes. It uses specific verbs ('check', 'walks the ladder') and resource names ('CLOB order-book depth', 'polymarket_arbitrage', 'polymarket_edges'), making its purpose distinct from sibling tools.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also implies when not to use (small trades) and warns about risks of partial basket fills, providing clear usage boundaries.

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 and idempotent behavior. The description goes far beyond by detailing compatibility_warning conditions (bet shape mismatches, semantic unrelatedness), temporal alignment, and skipped cross-type/subtype counters. No contradictions with annotations.

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

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

The description is long but every sentence provides unique value. It could be slightly more concise, but it is well-structured with clear sections for modes, response, and safety fields.

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

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

Given the complexity of a cross-venue spread tool and the absence of an output schema, the description is remarkably complete. It covers all inputs, behavior, response structure, and edge cases like compatibility warnings and temporal mismatches.

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 each parameter has a description. The description adds further context: override behavior for explicit parameters and the list of valid topic values. This adds significant 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs and resources. It distinguishes from sibling tools by focusing on this specific pair of prediction markets.

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

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

It explicitly describes two usage modes (topic shortcuts vs explicit tickers), provides examples, and warns that pre-mapped topics often yield compatibility warnings. This tells the agent when to use which mode and sets realistic expectations.

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. Description adds value beyond annotations by explaining the scoping mechanism and the behavior of omitting the key (listing all keys). No contradictions.

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

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

Two sentences with zero waste. First sentence states core function, second provides usage context and pairing. Highly efficient and front-loaded.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers both use cases, scope, and relationship to sibling tools. No gaps remain.

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

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

Schema coverage is 100% for the single parameter. Description adds crucial semantic info: omitting key lists all saved keys. This clarifies the parameter's optionality and alternative behavior beyond the schema definition.

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 uses specific verbs 'retrieve' and 'list' with clear resource 'value previously saved via remember' and 'saved keys'. It distinguishes itself from siblings 'remember' and 'forget' by naming them and explaining the relationship.

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 context of when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget. Lacks explicit exclusions (e.g., when not to use) but still guides effectively.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds details about return fields, filtering, mark_read behavior, and polling suitability, providing rich 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?

Description is three sentences: first establishes purpose, second details return content and filters, third discusses read tracking and alternative access. Every sentence adds value, no redundancy.

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

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

For a read-only tool with no output schema, the description covers what events carry, filtering options, and read behavior. It is complete enough given the tool's simplicity and sibling context.

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

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

All 5 parameters are fully documented in the schema (100% coverage). Description adds meaningful usage examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains the effect of mark_read, enhancing understanding beyond the schema.

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

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

Description clearly states the tool pulls fired events from a subscription feed, specifying the exact resource and action. It distinguishes itself from sibling tools by focusing on recent alerts from the persisted feed.

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

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

Description explains when to use the tool (e.g., polling, filtering by type and since) and provides an alternative access method (GET endpoint). It lacks explicit when-not-to-use instructions 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: parallel calls to multiple sources, fallback logic, soft-fail for patents, and the return shape (changes[] grouped by source, total_changes, pipeworx:// URIs). 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 compact and front-loaded with practical examples. Each sentence earns its place, though it could be slightly trimmed without losing clarity. The structure effectively guides understanding from purpose to nuance.

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 3-required-parameter tool with no output schema, the description sufficiently explains the return structure (changes[] grouped by source, total_changes, citation URIs) and edge cases (patents soft-fail, news fallback). An agent can fully understand inputs and outputs.

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

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

Schema coverage is 100%, so the schema already documents all params. The description adds value by providing usage examples for since (ISO date, relative shorthand, and recommended '30d' or '1m') and value (ticker, CIK with examples). This extra context aids correct invocation.

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

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

The description opens with concrete example queries ('What's new with X', 'latest on Y') and explicitly states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes from sibling entity_profile by directing when to use that alternative.

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 guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' It also details fallback behavior (GDELT→GNews) and soft-fail conditions for patents, giving clear when-to-use and when-not-to-use 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?

Discloses beyond annotations: data scoped by identifier, persistence (24h for anonymous, permanent for authenticated). Aligns with annotations (idempotentHint=true, destructiveHint=false) and adds value without contradiction.

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

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

Single well-structured paragraph. Front-loaded with main purpose, followed by usage and behavioral details. Every sentence earns its place, 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?

Given simple schema (2 string params, no output schema), the description is fully complete: explains scoping, persistence, and usage context. No gaps for an agent to understand 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 100%, but description adds meaning by providing examples for key (e.g., 'subject_property') and explaining value as 'any text — findings, addresses, preferences, notes', enriching the schema.

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

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

Clearly states the tool saves data for later reuse, with specific examples (ticker, address, preference). Distinguishes from siblings 'recall' and 'forget' by naming them explicitly as complementary tools.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and when not (implicitly when data is not needed). Provides context for authentication differences and pairing with recall/forget.

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

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

Annotations already mark it read-only and idempotent. The description adds behavior: identifiers are labelled with source, unresolved identifiers are explicitly listed, and enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable. This transparency about failure modes and fallback behavior goes beyond the structured 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 detailed but somewhat verbose, with long clauses and embedded lists. It front-loads with examples and 'Use FIRST' guidance, but the SUPPORTED TYPES section is dense. It could be streamlined, but every sentence conveys useful information.

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

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

Despite lacking an output schema, the description covers return behavior (source-labelled identifiers, `unresolved` field, specific RxNorm citation format) and graceful degradation. It gives enough context for an agent to know what to expect and when to fall back.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds examples ('AAPL', '0000320193', 'ozempic') and explains supported types, but the input semantics are already well-specified in the schema. It doesn't add significant new parameter-level meaning.

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

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

The description opens with concrete user queries and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly identifies the verb+resource and differentiates from siblings by listing supported types ('company', 'drug') and explaining it replaces manual lookups.

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

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

The instruction 'Use FIRST whenever you have a name but need an ID' provides an explicit usage trigger, and the example queries clarify when to invoke. However, it does not name alternative tools or explicitly say when not to use it, leaving some ambiguity with sibling search 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, and destructiveHint. The description adds that it probes via ai_visibility_check and returns a ranked list with specific fields (score, confidence, signal density), providing behavioral context beyond annotations.

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

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

Two sentences: first states core functionality, second gives use case and output structure. No wasted words, front-loaded.

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

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

Description covers what the tool does, how it works (via ai_visibility_check), what output to expect (ranked list with score, confidence, signal density), and a concrete use case. Adequate for the complexity without output schema.

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

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

Schema covers 100% of parameters. The description adds extra semantics for the entities parameter (first entry is the subject, rest are competitors) and explains the purpose of models and _apiKey, adding value beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, ranks scores, and outputs a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and 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 gives a clear use case (competitive AI-marketing audits) and implies that for single entity probes one should use ai_visibility_check. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant behavioral context: composite fan-out across external services, partial degradation, 5-30s first measurement from bundlephobia, and the sources_failed field. 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 moderately concise with front-loaded purpose. Each sentence contributes value: scope, alternatives, return structure, timing, error handling. Slightly verbose but 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 no output schema, the description details return fields (summary block, advisories, links, alternative versions) and error behavior (sources_failed). Lacks exact format of some fields, but covers the essentials. Annotations provide safety context.

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

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

Schema coverage is 100% (both parameters have descriptions). The description elaborates on the package parameter (accepts scoped packages) and version (defaults to latest), but adds little beyond the schema's own descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check combining deps.dev and bundlephobia. It specifies the resource (npm packages) and the verb (checking safety, popularity, size). No sibling tool serves the same function, distinguishing it well.

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 the tool when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It notes the NPM-only scope with a fallback for other ecosystems, but does not provide explicit '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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it is keyless and uses an offline NLM source, but does not discuss rate limits, auth, or side effects beyond what annotations cover.

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 two-sentence description plus example is highly concise and front-loaded with the purpose. Every sentence adds value, with no wasted words.

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

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

For a simple search tool with good annotations and schema, the description is mostly complete. It explains the source, input, and example output. Minor omission: it does not specify if multiple results can be returned or pagination, but given the example list, it's 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 both parameters documented. The description reinforces that 'query' can be a condition or code and provides an example, but adds minimal extra beyond schema descriptions.

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

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

The description clearly states the tool searches ICD-10-CM diagnosis/billing codes by keyword or code, with a concrete example. It distinguishes this tool from siblings like search_loinc by being specific to ICD-10 codes.

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

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

The description implies usage for ICD-10 code lookup but does not explicitly state when to use this tool vs alternatives (e.g., search_loinc, search_medical_terms). No exclusions or when-not guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by clarifying the return format ('LOINC number + long common name') and that the search is 'keyless', which is not captured in annotations or schema.

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 short, front-loaded sentences plus an example; every sentence serves a purpose. No redundant or vague phrasing.

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 search tool with full schema coverage and rich annotations, the description adequately covers purpose, usage, output format, and behavioral traits. Minor omissions like pagination or sorting are acceptable given tool 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 clear descriptions for both parameters ('query' and 'limit'). The description's example reinforces usage but does not add new semantic details beyond what the schema already provides.

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

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

The description clearly states the verb 'Search' and resource 'LOINC codes', specifies the method 'by keyword (keyless)', and provides an example mapping a query to output fields. It distinguishes from sibling tools like search_icd10 by targeting a unique code system.

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 context through the example and domain mention ('lab tests & clinical observations'), but does not explicitly state when to avoid this tool or compare with alternatives like search_medical_terms. The example provides practical 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'keyless' which aligns with openWorldHint but does not provide additional behavioral traits beyond what annotations already convey.

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

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

The description is a single sentence that is front-loaded with the core purpose ('Search clinical term lists by keyword') and efficiently adds the permissible systems. No unnecessary words.

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

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

Given the tool's simplicity, comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint), and full schema coverage, the description adequately covers what an agent needs to correctly invoke the tool. It explains the key customization point (system parameter) without needing to restate schema details.

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 explicitly mapping the 'system' parameter values to their meanings (conditions=problem/diagnosis names, procedures=procedure names, drugs=RxTerms drug display names), which is not fully captured in the schema's single-line description.

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

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

The description clearly states the tool searches clinical term lists by keyword, specifying three specific systems (conditions, procedures, drugs). This distinguishes it from sibling tools like search_icd10 and search_loinc, which target specific code sets.

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 no guidance on when to use this tool versus alternatives like search_icd10 or search_loinc. It does not include any exclusions or context for choosing one system over another.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description reveals the embedding model (BGE-base-en), windowing (500-char overlapping), truncation at 200K chars with a flag, and that passages include offsets for verification.

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

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

The description is concise (5 sentences) with no fluff. It is front-loaded with the core purpose and includes all critical details in a well-organized manner.

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 3-parameter tool with no output schema, the description covers inputs, outputs (passages with offsets/scores), technical behavior, limitations (truncation), and usage context. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (e.g., example queries, default limit, max chars) but does not add new constraints beyond what the schema provides.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with offsets. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining how it complements 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 explicitly advises using the tool when a record is too large for the prompt, saving context. It suggests pairing with ask_pipeworx_grounded, but does not explicitly exclude smaller records.

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 mutability (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds context beyond annotations: delivery channel details, SMS caps, webhook auto-disabling, and auth requirements. However, it does not clarify behavior if a subscription already exists (idempotency details missing).

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

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

The description is a single paragraph that front-loads the main action and then provides details. It is dense but efficient, though it could potentially be broken into bullet points for easier consumption.

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 (nested objects, 3 params, no output schema), the description covers the main functional aspects: purpose, supported types, delivery options, and auth. Missing details include error handling and exact response format, but the lack of output schema limits expectation.

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. The description adds significant meaning: explains each subscription type's parameters (e.g., sec_8k items codes, polymarket topic), delivery constraints, and validation rules. This is more than a simple restatement.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. The verb 'create' and resource 'subscription' are specific. It distinguishes from sibling tools like list_subscriptions and unsubscribe implicitly.

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 some guidance on prerequisites (OAuth account) and supported types, but does not explicitly compare to alternatives or state when not to use this tool. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the response format (category-bucketed examples) and that it's drawn from a live catalog, which is helpful. No contradictions.

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

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

The description is somewhat lengthy but well-structured, front-loaded with alternative queries, and every sentence provides useful information. Minor room for tighter phrasing.

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

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

Given no output schema, the description thoroughly explains what the tool returns (category-bucketed examples with tool+argument shapes). It covers purpose, usage, parameter, and behavioral context, making it complete for an onboarding tool.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema by explaining the optional topic parameter with examples ('finance', 'pharma') and clarifying behavior when omitted. It also mentions the full spread without arguments.

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

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

The description explicitly states it is the onboarding entry point, returning category-bucketed example questions with tool+argument shapes. It uses specific verbs and resources, and distinguishes itself from siblings like ask_pipeworx and discover_tools.

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

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

The description clearly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains omitting the topic for a full spread or passing a topic to focus. It provides clear context but 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?

The description reveals key behavioral details beyond annotations: ownership enforcement, soft deactivation (not deletion), and that historical events remain accessible. Annotations include idempotentHint=true and destructiveHint=false, which align with the description. No contradictions.

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

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

Two concise sentences: first states the action, second adds critical behavioral and ownership context. No redundant 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 a single parameter, no output schema, and annotations covering safety (non-destructive, idempotent), the description fully informs an agent about ownership enforcement and deactivation 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?

The input schema covers the single parameter 'id' with a clear description (uuid returned by subscribe). The tool description adds no extra semantic value beyond the schema. Baseline 3 for 100% 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 'Cancel a subscription by id', specifying the verb and resource. It implicitly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when to use. No explicit when-not-to-use or alternatives, but the constraint is well communicated.

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?

Despite strong annotations (readOnly, idempotent, openWorld, non-destructive), the description adds critical behavioral nuance: it explains the meaning of each verdict, especially the distinction between could_not_verify (check failed, no evidence) and unsupported (no source found). It also discloses that evidence includes pipeworx:// citations and that tolerance can be overridden for hallucination detection—none of this is in the annotations.

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

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

The description is longer than average but every sentence earns its place. It starts with concrete examples, then explains the two paths (structured vs. grounded), lists verdicts, clarifies error semantics, and ends with the value proposition. No filler or repetition—it is dense but highly scannable.

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 covers return values (verdict, actual value, citation, reasoning) and error handling (verification_error with stage and detail). It also explains edge cases (could_not_verify vs unsupported) and positions the tool's efficiency gain. Given the tool's complexity, this is a complete and self-sufficient description.

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

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

Schema already covers 100% of parameters with descriptive text. The description goes further by explaining the tolerance_pct default behavior ('capped at 5') and how to use it (1–2 for hallucination detection), and describes the internal math ('exact percent-delta math') for financial claims, adding context beyond the schema's static 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 opens with explicit trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes this from sibling tools by stating it 'Replaces 4–6 sequential calls' and covers both structured financial verification and grounded fallback for all other claims.

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 the agent needs to check whether something a user said is factually correct.' It also explains routing logic (SEC EDGAR for financial claims, grounded pipeline otherwise) and gives a clear exclusion: could_not_verify must not be treated as evidence. This is more specific than typical 'use when' guidance.

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