Epss

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

Discloses behavioral traits beyond annotations: default model (Workers AI), optional Anthropic probe with BYO key, billing responsibility, return structure (per-model and combined view). 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?

Description is informative but not overly verbose. Front-loaded with main action. Could be slightly tighter, but every sentence earns its place.

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

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

Given no output schema, description explains return structure (per-model with score, confidence, signals, raw_response, plus combined view). Covers parameters, usage, and output sufficiently.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining default model for `models`, that `_apiKey` is BYO key, and that `context` helps disambiguate. Adds meaningful context.

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

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

Clearly states it probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. The verb 'probe' and resource 'LLMs for visibility' is specific. Distinguishes from sibling tools by focusing on AI-marketing audits, pre-launch checks, and competitive monitoring.

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 clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not explicitly list when not to use or alternatives, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond those: it routes among 5,635 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and notes it makes one fast call on every tier. This enriches the behavioral picture without contradicting any annotation.

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

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

The description is long but front-loaded: it opens with 'PREFER OVER WEB SEARCH' and the core scope. It contains multiple distinct pieces (scope, examples, step-up guidance) with clear structure. Every sentence earns its place, though some pruning of the examples list could tighten it further.

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

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

Given the tool's complexity (routing across thousands of tools) and the absence of an output schema, the description adequately explains the return format (structured answer with citation URIs). It covers when to use, when not to, and alternatives. It doesn't mention error handling or rate limits, but those are not critical for selection and invocation in most cases.

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

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

Schema coverage is 100%, so the description need not compensate. The schema already describes the 'question' parameter and its aliases. The description adds examples and phrasing cues but no new parameter-level semantic details; it relies on the schema's own examples. Baseline of 3 is appropriate given high coverage.

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

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

The description clearly states the tool routes factual questions to a large set of verified sources and returns structured answers with citations. It lists specific data domains (SEC, FDA, FRED/BLS, etc.) and provides concrete examples, making the purpose unambiguous and distinguishing it from known siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, positions as the default entry point, and gives precise step-up conditions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part queries. It also covers breaking-news scenarios. This is textbook-grade 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 cover read-only, open-world, idempotent, and non-destructive traits. The description adds valuable context: no candidate is active right now, so behavior matches ask_pipeworx exactly; it is a full working router, not a fallback stub; and it represents the experimental edge. This goes beyond annotations and clarifies current behavior and expectations.

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

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

The description is informative and well-structured, starting with the beta identity, then current state, usage instruction, and a final clarifying statement. It is slightly verbose but each sentence earns its place, covering identity, state, usage, and the fact it's a full router. No fluff.

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

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

For a routing tool with a single question parameter, the description covers the purpose, usage, current behavioral state, and relationship to siblings. The shared response shape is mentioned, and the schema handles parameters. The only minor gap is no explicit mention of potential output differences when a candidate is active, but that's covered by 'candidate routing improvements' and the 'experimental' label.

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

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

Schema coverage is 100% and the schema describes the 'question' parameter and its aliases. The description mentions 'same arguments' as ask_pipeworx but does not add new meaning beyond the schema. Since coverage is high, a baseline of 3 is appropriate; the description adds no extra parameter insights.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by its experimental routing improvements and current inactive candidate state. The purpose is specific and unambiguous.

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

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

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and that results are compared against the stable router to decide merges. It also confirms that currently it matches ask_pipeworx exactly. While it doesn't enumerate alternatives like ask_pipeworx_grounded, it provides clear context for when to choose this beta over the stable router.

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

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

The description discloses behavioral traits beyond the annotations: it returns a structured object with `answer`, `evidence` (verbatim quote), `confidence`, `source`, etc., and an explicit refusal mechanism with specific reasons (`not_in_source`, `no_tool_match`, etc.). It also states the operational cost (one extra LLM call). The annotations already declare read-only, idempotent, and open-world, but the description adds critical context about refusal semantics and data handling. 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?

Despite being long, every sentence adds value: purpose, routing, extraction, return format, refusal reasons, use cases, and cost. It is front-loaded with the primary purpose and the key differentiator ('Same routing as ask_pipeworx...'). No fluff or repetition. The structure efficiently guides the agent to key decisions (when to use, what to expect).

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 meta-tool that routes to 5,635 tools, the description thoroughly explains the input (natural language question), the return format in both success and failure cases, and the costs. The absence of an output schema is compensated by a detailed description of the response object and refusal reasons. An agent has everything needed to decide to call it and interpret the result 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 a single required `question` parameter and five aliases (q, text, input, query, prompt). The description does not add further parameter semantics—it says 'Your question in natural language' but that's already in the schema. It discusses internal argument filling for the routed tool, but that's about the inner process, not the parameter meaning. Baseline 3 is appropriate because the schema fully explains the parameter.

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

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

The description states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clarifies the mechanism (routing to the right tool from 5,635 options, then extracting the answer solely from the result) and distinguishes itself from the sibling `ask_pipeworx` by the added extraction step and explicit refusal behavior. The verb 'ask' and resource 'Pipeworx' with 'grounded' modifier are clear.

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

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

Explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also gives the when-not-to-use by preferring `ask_pipeworx` for casual lookups and mentions the cost trade-off of 'one extra LLM call.' No ambiguity about 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 discloses extensive behavioral traits beyond annotations: low-confidence short-circuit, closed market handling, wide-spread warnings, cancellation rule parsing, parent event extraction, and raw data mode. Annotations indicate read-only, open-world, idempotent behavior, and the description aligns perfectly with 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 very long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), front-loading the main purpose. While comprehensive, some details (like specific fan-out examples) could be condensed without losing clarity, but the organization aids navigation.

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

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

Given the tool's complexity (multiple data sources, safety checks, edge cases), the description is highly complete. It covers low-confidence matches, closed markets, cancellation rules, illiquid spreads, parent events, and raw data mode. No output schema exists, but response shapes are adequately explained.

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

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

Schema coverage is 100%, and the description adds significant meaning: 'market' can be slug, URL, or question text; 'depth' explains quick vs thorough; 'include_raw' specifies when to use true. Examples in the schema further clarify parameter use.

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 researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, and fanning out to evidence. It lists specific use cases ('should I bet on X', 'what does the data say', 'is there edge') and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges through its unique multi-source data aggregation.

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: for betting research questions. It provides examples and classifiers. However, it does not explicitly state when not to use it or compare directly to alternative tools, though the detailed behavior implies 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 provide readOnlyHint=true and idempotentHint=true, indicating safe, repeatable reads. The description adds significant value: it reveals the data source (SEC EDGAR/XBRL for companies, FAERS for drugs), discloses handling of off-calendar fiscal years, and notes the sorted output ordering. These details help the agent understand what to expect beyond the annotations. No contradictions.

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

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

The description is well-structured, starting with usage examples then diving into behavioral details. Every sentence adds unique information. It is concise for the amount of content covered, though slightly verbose in listing all example phrases. A minor improvement could be to tighten the opening list of triggers, but overall it earns its length.

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

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

For a tool with 2 parameters and no output schema, this description is remarkably complete. It explains the data sources, output ordering, citation URIs, and efficiency gains. There are no gaps: the agent knows exactly what data to expect and how to invoke the tool correctly. The description fully compensates for the lack of 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?

Schema coverage is 100% (both 'type' and 'values' have descriptions). The description adds meaning: it clarifies that 'values' should be tickers/CIKs for companies and drug names for drugs, and it explains that 'type' determines the data source and metrics. It also prescribes maxItems=5 and minItems=2, reinforcing schema constraints. This is helpful context beyond the raw schema.

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

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

The description explicitly defines the tool's function: side-by-side comparison of 2–5 companies or drugs. It provides specific examples of natural language triggers ('compare X and Y', 'which is bigger') and distinguishes the tool from single-entity lookups by emphasizing parallel calls. The verb 'compare' combined with resource entities clearly communicates the core purpose.

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

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

The description gives precise when-to-use guidance with explicit commands like 'ALWAYS PREFER over sequential single-pack lookups'. It covers the intended scenarios (comparison, ranking) and even provides the number of sequential calls saved. While it doesn't explicitly list when not to use, the sibling context (e.g., 'entity_profile' for single entities) implies alternatives. A small gap: no mention of prerequisites or data freshness.

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, so the safety profile is covered. The description adds substantial behavioral context on top: account/plan requirements (paid tier for 'thorough'), timing windows (15-60s, up to ~90s), the guaranteed-not-invented gaps[] behavior, the hop field and citation_uri present only when fetchable, semantic (non-head-truncated) excerpting, and the contradictions[] pass. This is rich, non-redundant disclosure.

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

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

Every sentence earns its place and there is zero fluff, but the description is a single dense wall of long, nested run-on sentences (e.g., multiple parentheticals and em-dash clauses stacked together). It is front-loaded with the account requirement, which is good, but this volume of information would benefit from shorter sentences or clearer segmentation to aid agent parsing. Appropriately comprehensive, but not well-structured.

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

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

For a high-complexity tool with no output schema, the description carries the full burden of explaining return behavior and does so thoroughly: the findings packet (verbatim evidence + confidence + source + fetched_at + citation_uri), gaps[] for unanswered facets, contradictions[], and the hop field. With 2 simple parameters and no nested objects, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema's enum text for depth — it explains the iterative second-hop behavior (gap recovery, lead-chasing), the timing impact, and the contradictions[] scan differences between 'standard' and 'thorough'. The question parameter is self-evident. This earns one point above baseline.

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

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

The description states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources' in ONE call, and explicitly distinguishes it from open-web search ('this is NOT open-web search'). It names sibling ask_pipeworx as the alternative for single lookups, giving an agent a crisp mental model without opening any schema.

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

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

Usage guidance is exhaustive and precise. It states when to use this tool ('Best for broad/multi-part questions over structured data') and explicitly names the conditions that select alternatives: use ask_pipeworx for single lookups, for BREAKING/current-news topics ('it routes to live news APIs'), and when not signed in. No inference is left to the agent.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description adds context: results are 'top-N most relevant', include 'curated examples', and are '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 purpose and usage, though slightly lengthy due to listing domains. Every sentence adds value, but could be trimmed slightly.

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

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

The description fully explains what the tool does, when to use it, what it returns, and provides examples. No output schema exists, but the description compensates by describing the output nature.

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

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

Schema description coverage is 100%, so the schema already defines parameters well. The description provides example queries and mentions aliases, but adds limited extra meaning beyond what the schema offers.

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 discovers tools by describing a data or task, and explicitly lists many domains. It distinguishes itself from siblings by emphasizing it returns ready-to-call tools with full schemas.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set'. It also provides a list of example queries, guiding the agent on when to use this tool.

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

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

Discloses internal fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), mentions patent soft-fail after May 2025, and describes return fields in detail. Annotations already provide readOnlyHint, openWorldHint, etc., and description adds non-contradicting context.

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 query examples and a clear directive, then systematically details returns. While slightly lengthy, every sentence contributes necessary information; 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?

Given no output schema, the description fully explains all return fields, including fallback mechanisms (GDELT→GNews), soft-fail behavior, and sorting. It covers prerequisites, limitations, and provides a complete mental model for the tool's behavior.

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

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

Schema coverage is 100%, but description adds significant value: clarifies type enum only 'company', explains value format (ticker or zero-padded CIK), warns about name vs. identifier disambiguation, and provides examples ('AAPL', '0000320193').

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 a 'full cross-source profile of a US public company in ONE parallel call' with specific examples ('Tell me about X', 'research Acme'), and distinguishes from siblings like resolve_entity and compare_entities by specifying when to use each.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and gives exclusion guidance: 'Names not supported (use resolve_entity first if you only have a name)'. Clearly advises when not to use.

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

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

Annotations already declare destructiveHint=true, and the description confirms 'delete' behavior. It adds context about clearing sensitive data and that memories are previously stored. No contradiction. Could mention error handling for nonexistent keys, but overall aligned with annotations.

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

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

Two sentences, no redundancy. Each sentence earns its place: one for core action, one for usage guidance. Efficient and clear.

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

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

Given low complexity (one parameter, no output schema) and annotations covering destructiveness, the description is sufficient. It provides purpose and usage cues. Could include a note on idempotency or error behavior for complete coverage, but not necessary for basic use.

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

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

Schema coverage is 100% and parameter description ('Memory key to delete') is self-explanatory. The tool description adds no additional parameter insight beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly defines the action (delete) and resource (memory by key). It distinguishes from siblings by pairing with 'remember' and 'recall'. The verb and resource are specific and unambiguous.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, or clearing sensitive data. Mentions pairing with siblings for context. Does not include when-not-to-use or alternatives beyond siblings, but the guidance is clear and practical.

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, idempotentHint, etc.) already indicate safety and non-destructiveness. The description adds context about fetching the page, extracting title/description/links, and emitting a standard format. This aligns with annotations and provides useful behavioral detail 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 concise (3 sentences), front-loaded with the main action, and every sentence serves a purpose: what it does, how it works, and use cases. No wasted words.

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

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

Given the tool has only 2 parameters, no output schema, and annotations cover behavioral aspects, the description is complete. It explains the input (URL), the process, and the output (text blob), which is sufficient for correct 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?

The input schema covers 100% of parameters (url and max_links) with descriptions. The tool description does not add any parameter-specific details beyond what the schema already provides, so it adds no extra value to parameter understanding.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifies its purpose for AI crawlers, and describes the extraction and output format. It distinguishes this tool from siblings by focusing specifically on llms.txt generation, which is unique among the listed 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 lists explicit use cases (client indexing, own project, competitor auditing) but does not provide guidance on when NOT to use this tool or mention alternatives. Since siblings include 'scan_competitor_ai_presence', which could overlap, the lack of exclusions slightly reduces the score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds value by clarifying the return format (score and percentile) and explaining the meaning of EPSS and its relationship to CVSS, which aids in interpretation.

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

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

The description is two sentences, front-loaded with the core purpose and output format, followed by a brief use case. No redundant information; every sentence contributes 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 a single parameter, no output schema, and comprehensive annotations, the description adequately explains what the tool returns and how to interpret results. It could mention potential input limits (e.g., maximum CVEs per request) but is still complete for typical 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 description coverage is 100%, so the baseline is 3. The tool description does not add additional meaning to the 'cve' parameter beyond what the schema already provides (single CVE or comma-separated list). The description focuses on output rather than input details.

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

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

The description explicitly states the tool retrieves EPSS exploit-probability for one or more CVEs, specifying the score range (0-1) and percentile. It clearly identifies the resource (EPSS for CVEs) and the action (get/return), distinguishing it from siblings like top_exploited which focus on top vulnerabilities.

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 advises using the tool to gauge real-world exploit likelihood and prioritize patching, and explains how it complements CVSS severity. While it does not list specific alternatives or when-not-to-use scenarios, the context provided is sufficient for an agent to understand its primary use case.

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

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

Annotations already indicate readOnlyHint and destructiveHint. The description adds context that it returns active subscriptions by default and lists specific fields, providing behavioral clarity beyond annotations.

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

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

Two concise sentences: first states purpose and output, second gives usage guidance. No unnecessary words, front-loaded with purpose.

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

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

Given the single optional parameter, no output schema, and comprehensive annotations, the description is complete. It covers purpose, output fields, default behavior, and use cases.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The description does not add additional meaning beyond the schema, but baseline 3 is appropriate since schema is sufficient.

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 'List' and the resource 'subscriptions', and specifies the return fields (id, type, params, created_at, etc.), distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It clearly states when to use the tool, though it does not explicitly mention when not to use it.

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

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

Annotations are all false/null, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), account-less claim_token behavior, and that it's free and doesn't count against quota. It doesn't explicitly state data retention or side effects of submitting, but the write nature is implied. No contradiction with annotations, and the added context is significant.

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 serves a purpose: purpose, use cases, exclusions, naming guidance, claim_token flow, operational details, rate limit, and cost. It is front-loaded with the main action and well-structured. It is not bloated, though it exceeds the two-sentence ideal; the complexity justifies the length.

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

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

For a tool with 4 optional params and no output schema, the description is comprehensive: it explains the main flow, the claim_token return, when to use it, scope restrictions, and operational policies. It could add explicit success/failure output examples, but the absence of an output schema is compensated by describing the claim_token return. Overall, it is quite complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful nuance beyond schema: the message should not include the end-user's prompt, claim_token usage is explained as a follow-up mechanism, and the enum categories are contextualized with examples. This elevates it above baseline.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific categories (bug, feature, data_gap, praise) and explicitly distinguishes itself from siblings by limiting scope to 'tools served by this Pipeworx connection,' which differentiates it from ask_pipeworx or other MCP 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 gives explicit when-to-use conditions for each feedback type, plus an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also provides instructions on what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and how to use the claim_token for follow-up. This is a model of usage guidance.

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

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

Annotations already declare read-only and idempotent behavior. Description adds value by noting caching duration (5min-1h) and that it derives from CF analytics with no PII, 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?

Description is concise (~4 lines), front-loads the main purpose, and every sentence adds value. No redundant or filler content.

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

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

Given one optional parameter and no output schema, the description sufficiently explains the return types (tools, packs, volume) and caching. It could be marginally improved by specifying the output structure, but is complete enough for a simple read-only tool.

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

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

Schema covers the parameter fully with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' aiding interpretation beyond schema.

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

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

Description starts with a clear verb+resource: 'What other AI agents are calling on Pipeworx right now.' Specifies returns (top tools, top packs, total call volume) and window options. Distinguishes from sibling tools like 'discover_tools' by focusing on trending usage rather than general discovery.

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

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

Explicitly lists three use cases with examples, providing clear context for when to use. Does not explicitly state when not to use or name alternatives, but the use cases are specific enough to guide appropriate selection.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description richly adds behavioral context: it describes the scanning scope (top ~200 markets), partition check logic (sum ≈1, deviations >3pp), semantic similarity threshold (≥0.30 Jaccard), placeholder filtering (>20% placeholder returns null), and fill check against live CLOB depth with actionable guidance (do not trade if realizable_edge_pp ≤ 0). 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, with clear sections for semantic anchor, partition filter, and fill check. While it is lengthy, every sentence adds value. A minor improvement could be making the fill check a separate note, but it remains highly organized and front-loaded with the main purpose.

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

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

For a complex arbitrage detection tool, the description covers all critical aspects: modes, parameters, internal logic, output structure (fields like gap_pp, suggested_trade, monotonicity context), and fill check with book depth. It also mentions a sibling tool for custom sizing. Despite no output schema, the description sufficiently explains the response.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context: for `event`, it explains slug format and provides examples; for `topic`, it explains cross-event scanning and gives example seed questions. It also clarifies behavior when no args are passed. This significantly enriches the schema.

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

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

The description clearly states the tool identifies arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, making the purpose immediately understandable and differentiating it 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 provides explicit when-to-use guidance for each parameter: no args for trending scan, event for specific market, topic for cross-event scan. It recommends event mode for specific markets and explains when cross-event mode catches missed patterns. It also details semantic anchor and partition filter conditions, giving 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description adds rich behavioral context: caching behavior (1h at KV level), computation details for each segment, edge and Kelly calculations, and diagnostic output. 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 verbose, containing detailed formulas and Greek letters. While comprehensive, it could be more concise and better structured for quick scanning. Every sentence adds value, but the length is borderline excessive.

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

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

Given the complexity (9 parameters, no output schema), the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), caching, and knobs. It compensates well for the missing 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?

All 9 parameters have schema descriptions, but the tool description adds significant context, such as explaining 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and distinguishing min_kelly from min_partition_leg_kelly. This enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on model-driven insights rather than pure arbitrage or tracking.

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

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

The description explicitly targets 'what should I bet on today' and explains the three segments. However, it does not explicitly state when to avoid this tool in favor of alternatives like polymarket_fill_risk or polymarket_arbitrage.

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 (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: it uses snapshots, computes trend and decay metrics, notes limits like 60-day TTL and daily closes only, and explains the response structure. No contradiction with annotations.

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

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

The description is relatively long but well front-loaded with the core purpose. It uses clear structure (RESPONSE with subsections) but could be slightly more concise or broken into bullet points for easier parsing. Every sentence adds value, though.

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 2 optional parameters with 100% schema coverage, no output schema, and the tool's complexity, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) and limitations (TTL, daily data). It adequately prepares an agent to interpret results without needing additional context.

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

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

With 100% schema coverage, baseline is 3. The description adds value by clarifying that 'days' is a lookback (default 14, clamp 2-30) and 'window' is the snapshot family (24hr/1wk/1mo, default 1wk). This extra context helps the agent understand defaults and constraints 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: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb (answers) and resource (edge persistence/decay), and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description tells when to use it: to understand how long an edge has existed and whether it is shrinking. It contrasts fresh wide edges with older ones, implying when the tool is relevant. However, it does not explicitly state when not to use it or provide alternatives, though sibling context suggests alternatives like polymarket_edges.

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 behavioral details like walking the order book ladder, returning verdicts, and explaining basket fill risks, which complements annotations without contradiction.

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

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

The description is dense but well-structured with bold key terms and line breaks. It is slightly long but every sentence adds value; minor trimming could improve conciseness.

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

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

Despite no output schema, the description thoroughly explains all return values for both modes, covers edge cases like thin legs and forced directional risk, and addresses potential pitfalls. It provides complete context for the tool.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it explains the auto side selection for baskets, clarifies size_usd interpretation per mode, and outlines defaults. This exceeds 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 it performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit guidance on when to use: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also warns about risks like partial basket fills converting arb into directional positions.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds significant behavioral context: explains the two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counts), and warns about the relevance of spreads based on bet shape equivalence. 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 verbose but front-loaded with the core purpose. Every sentence adds value, but it could be more structured with paragraphs for readability. Still, it is efficiently dense with 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 no output schema, the description thoroughly explains return values: leg-by-leg prices, spreads, compatibility fields, temporal alignment, and skipped counters. It covers all critical aspects for a complex tool like cross-venue spread calculation.

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 three parameters are fully covered in the schema. The description adds critical meaning: lists the 10 topic shortcuts, explains the override behavior of explicit params, and provides examples. Schema coverage is 100%, and the description enhances understanding beyond schema.

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

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

The description clearly states that the tool calculates cross-venue spreads between Kalshi and Polymarket for the same question, explains its two modes (topic and explicit), and distinguishes from sibling tools like polymarket_arbitrage by its specific cross-venue focus.

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

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

Provides explicit guidance on when to use each mode: topic for 10 pre-mapped macro shortcuts, explicit for custom pairings. Also warns that most pre-mapped topics return compatibility warnings and that spreads are rare, setting proper expectations for when the tool is useful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping (by identifier) and dual behavior (retrieve vs list), which is useful 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, no wasted words. Front-loaded with the core function, then usage and scoping. Highly efficient.

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

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

The description explains scoping, dual behavior, and sibling pairing. It does not explicitly describe return format, but it is adequately implied. No output schema present, but description is sufficient.

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

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

Schema coverage is 100% and already describes the parameter well. The description adds real-world context (e.g., user's target ticker) and reinforces the dual behavior based on key presence, adding value.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It distinguishes from siblings like remember and forget, and provides concrete examples (e.g., user's target ticker, address).

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 when to use the tool ('look up context the agent stored earlier') and pairs it with siblings (remember to save, forget to delete). Provides clear context for its 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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: the mark_read parameter flags events as read so subsequent calls return newer events, and the tool accesses a persisted feed. No contradictions with annotations.

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

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

The description is concise (3 sentences) and front-loaded, starting with the core purpose. Every sentence adds value, covering return fields, filter options, and alternative access. No redundant or vague language.

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

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

Given no output schema, the description lists what each alert carries (source, citation_uri, raw payload). It covers all inputs and explains their effects (e.g., mark_read, unread_only). It also mentions the alternative API, making it complete for a read-only retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value beyond the schema, e.g., explaining that mark_read=true ensures next call shows only newer events, and giving an example type ('sec_8k'). This extra context helps an agent use parameters effectively.

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

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

The description clearly states that the tool pulls fired events from a subscription feed and returns the most recent alerts with specific fields (source, citation_uri, raw event payload). It distinguishes from sibling tools by focusing on subscription feed alerts, which is distinct from general search or analysis 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 provides usage context: polling works fine, and the same feed is available via a direct API for scripts/dashboards. It explains filtering options (type, since, mark_read, unread_only). However, it does not explicitly state when not to use this tool or compare to siblings.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description reveals multi-source fan-out, fallback mechanism, PatentsView API sunset issue, and return format (citation URIs). No contradictions.

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

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

Single paragraph is dense with information but could be more scannable (e.g., bullet points). No wasted sentences; 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?

No output schema, but description sufficiently describes return structure (changes[], total_changes, citation URIs). Covers parameters, behavior, and alternatives, making it complete for an agent to invoke correctly.

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

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

Schema already describes all 3 parameters (100% coverage). Description adds value with examples of ISO dates and relative shorthands, and explains value accepts ticker or CIK.

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 ('returns structured changes[]'), names the resources (SEC EDGAR, GDELT, GNews, USPTO), and distinguishes from sibling 'entity_profile' by contrasting use cases ('what's new' vs 'static profile').

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

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

Explicitly tells when to use entity_profile instead, and provides context on fallback behavior (GDELT preferred, GNews on rate limit/5xx). Could add more explicit 'do not use when' scenarios, but the alternative is clearly stated.

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

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

Adds behavioral context beyond annotations: key-value storage scoped by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). Annotations indicate idempotentHint=true and destructiveHint=false, which description supports by implying storing same key again is safe. 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, front-loaded with purpose, then usage, then technical details. Every sentence adds value. No filler.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage guidelines, behavioral details, and parameter semantics. Complete and self-contained.

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

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

Schema coverage is 100%, but description adds value by providing examples of keys (subject_property, target_ticker, user_preference) and clarifying value can be any text. This helps the agent understand parameter usage beyond schema types. Baseline 3, +1 for extra guidance.

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 verb+resource: 'Save data the agent will need to reuse later'. Distinguishes from siblings recall and forget by mentioning pairing. Specific about what kinds of data (resolved ticker, target address, user preference, research subject).

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'. Mentions alternatives (recall to retrieve, forget to delete). Provides context about scoping (by identifier) and persistence differences for authenticated vs anonymous sessions.

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 readOnly/idempotent/destructive hints, but the description adds valuable behavioral detail: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling, and explicit disclosure of unresolved identifiers. This goes well beyond annotation basics.

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 tightly packed with essential information. It is front-loaded with examples and the core purpose, then systematically details supported types, behaviors, and caveats. Every sentence contributes to the agent's ability to select and invoke the tool correctly.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does so thoroughly: identifiers with source labels, unresolved list, drug result structure (RxCUI, ingredient, brand, citation). It also covers input edge cases like non-US issuers, making it complete for a complex tool.

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

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

While schema coverage is 100%, the description significantly enriches parameter meaning with examples (ticker, CIK, ISIN) and special handling (ISIN resolves to legal entity). It explains the enum values ('company', 'drug') in depth, detailing what each returns and the accepted input forms.

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

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

The description uses a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'). It includes concrete query examples, clearly distinguishing it from sibling tools like entity_profile or compare_entities by focusing on ID lookup.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, giving context on when to prioritize it. The supported types and input formats further clarify 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, destructiveHint, establishing a safe, read-only, exploratory tool. The description adds valuable behavioral details: it internally calls 'ai_visibility_check' for each entity, ranks by score, and returns scores, confidence, and signal density. No contradictions with annotations.

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

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

The description is concise, consisting of two well-structured sentences. The first sentence defines the core action and outcome; the second provides a concrete use case and output format. No extraneous information. Front-loaded with the most important information.

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

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

Despite lacking an output schema, the description compensates by explaining the return value (ranked list with score, confidence, signal density). It also explains the internal mechanism (probing each entity with ai_visibility_check). The tool's complexity is moderate, and the description covers all necessary aspects for correct use.

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

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

Schema description coverage is 100% with all parameters well-documented. The description adds little extra meaning for parameters beyond restating 'entities' as '2-8 entities'. It does not provide additional constraints or formatting hints beyond the schema. 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 compares AI visibility across multiple entities side-by-side. It specifies the action ('compare', 'probes', 'ranks', 'surfaces') and the resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling tool 'ai_visibility_check' by focusing on multiple entities and ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implies when to use (when comparing multiple entities), but does not explicitly state when not to use or mention alternatives like 'ai_visibility_check' for single-entity checks. The context is clear but lacks 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?

Beyond annotations (readOnlyHint, etc.), the description adds valuable behavioral details: fans out to two services, returns structured summary, per-advisory detail, links, alternatives. It also warns about bundlephobia's first measurement latency (5-30s) and graceful degradation via sources_failed. 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 sentences, each dense with information. Front-loaded with core purpose, then usage context, then detailed output and failure behavior. No redundant text; every sentence earns its place.

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

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

Given the complexity (composite tool with multiple sources, no output schema), the description fully specifies what is returned (summary fields, advisories, links, alternatives) and how failures are handled. It is sufficient for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% and descriptions are clear. The description adds extra context: scoped packages accepted for 'package', and default behavior for 'version' (already in schema but reinforced). This adds marginal value beyond schema.

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

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

The description clearly states it is a composite check for evaluating npm packages, specifying the exact resources (deps.dev and bundlephobia) and the query context. It distinguishes itself from siblings by focusing on npm ecosystem and multi-source aggregation.

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

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

Explicit guidance on when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also clearly states limitations: NPM only in v1, with fallback for other ecosystems. This helps the agent decide appropriately.

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), adds details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, passage offsets for verification. No contradiction with annotations.

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

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

Compact yet comprehensive: one sentence defines purpose, next explains use case and pairing, last discloses technical details. No filler.

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

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

No output schema, but description explains return values (passages with offsets and scores). Input constraints and model details provided. Fully equips an agent to decide and invoke.

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%; description adds meaningful context: 'text' max length and truncation behavior, 'query' examples, 'limit' default and range. This goes 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 performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It distinguishes itself from siblings by explaining its niche: searching within already-pulled text rather than fetching new data.

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

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

Explicitly says when to use (record too big for prompt, save context). Mentions pairing with ask_pipeworx_grounded. Could be more precise about when not to use, but context is clear.

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

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

Annotations indicate idempotentHint=true, so description aligns. Adds context: returns subscription id, requires OAuth, delivery channel behaviors (webhook HMAC, auto-disable after 10 failures). Does not clarify behavior if subscription already exists, but overall good.

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

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

Long but well-structured: core purpose first, then requirements, types, delivery channels. Every part earns its place. Slightly front-loaded. Minor room for improvement but efficient given 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?

Highly complete for a complex subscription tool with nested schema and no output schema. Covers all input details, return value, prerequisites, and channel behaviors. No gaps left for agent.

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

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

Schema coverage is 100%, but description adds significant meaning: explains type-specific params with examples (e.g., sec_8k items codes, polymarket_edge topic), and delivery options with details (sms verification, webhook signing). This goes well 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb 'create' and resource 'subscription' are specific, and it distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit guidance: prerequisites (Pipeworx OAuth account, no anonymous/BYO), supported types with examples, delivery channel conditions (feed always on, email/sms/webhook with caps and verification), and implicitly contrasts with read-only tools. Tells when not to use (anonymous users).

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, destructiveHint. The description adds that the tool returns example questions (not real data) and mentions the category structure. No contradiction. It provides useful behavioral context beyond the annotations.

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

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

The description is front-loaded with common questions and then explains functionality. Every sentence adds value. Could be slightly trimmed but overall well-structured for its informative role.

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 has one optional parameter, no output schema, and strong annotations. The description fully covers its purpose, usage, return format (categories, tool shapes), and when to call it. Nothing missing.

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

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

Schema coverage is 100% (one optional parameter with a clear description of its values and behavior). The description adds a minor extra example but is largely redundant with the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and distinguishes it from siblings like ask_pipeworx or discover_tools by positioning it as the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains when to omit or pass a topic. It implies this is for exploration, not direct queries, though it doesn't explicitly exclude sibling tools beyond that context.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive hints. Description adds value by explaining ranking by EPSS descending and defining EPSS as probability of exploitation in next 30 days, which is beyond annotation scope.

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, front-loaded with main purpose, and contains 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 tool's simplicity and full schema coverage, the description provides sufficient context about ranking method and EPSS meaning. Could mention return fields (CVE ID, score) but not critical.

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

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

Schema already has 100% coverage with clear descriptions for both parameters (limit and min_score). Description does not add new parameter-specific meaning beyond what schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states 'List the CVEs most likely to be exploited, ranked by EPSS score descending' and answers a specific question. It distinguishes from siblings by focusing on top exploited CVEs rather than individual EPSS queries.

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 suggests using the tool for patching prioritization, but does not explicitly state when not to use it or compare to alternatives like get_epss. The guidance is clear but lacks exclusion criteria.

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 value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain available. No contradiction with annotations.

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

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

The description is concise, consisting of three short sentences that are front-loaded with the key action. 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?

For a simple tool with one required parameter and no output schema, the description covers purpose, ownership, and behavioral details adequately.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description does not add additional meaning beyond the schema.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription', with ownership enforcement. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear context for when to use (cancel own subscriptions) and explains the behavior (deactivation vs deletion), but does not explicitly mention when not to use or list alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description enriches this by detailing two pipeline paths, returning a specific verdict enum, and warning that 'could_not_verify' means the check did not happen and 'must not be shown as one' of the evidence verdicts. It also clarifies the distinction between 'could_not_verify' and 'unsupported', adding error semantics that annotations cannot convey.

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

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

The description is long but information-dense, with no filler. It front-loads the purpose with example phrasings, then follows with routing, return semantics, a critical caveat, and an efficiency note; each sentence contributes meaningful operational detail, though the length is at the upper bound of 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?

There is no output schema, so the description compensates by enumerating the verdict values, the returned actual value with citation, and reasoning, while also defining the failure modes (could_not_verify with verification_error, unsupported). For a tool that replaces multiple sequential steps and has two routing paths, the description fully covers what the agent needs to invoke it and interpret results.

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

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

Both parameters (claim, tolerance_pct) are fully described in the schema with 100% coverage, including the tolerance override range and hallucination-detection guidance. The description adds only tangential context (e.g., 'exact percent-delta math') already implied by the schema, so it does not significantly enhance parameter understanding beyond the structured 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?

The description opens with example natural-language phrasings and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from general query tools by specifying a fast path for company-financial claims via SEC EDGAR/XBRL and a grounded pipeline for other factual claims, and notes it 'Replaces 4–6 sequential calls,' which separates it 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 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also explains the two routing paths (company-financial vs any other claim) and the efficiency benefit over sequential calls, but it does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls just short of a 5.

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