Energi Data Dk

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

Annotations already declare read-only behavior. Description adds operational details: default model, API key requirements, per-model return 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?

Three well-structured sentences. First sentence states main purpose, second adds key parameter details, third provides use cases. No redundant information.

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

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

Despite no output schema, description clearly states return format (per-model {score, confidence, signals, raw_response} + combined view). All 4 parameters are described in schema and description, making it fully complete for usage.

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

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

Schema coverage is 100% so baseline is 3. Description adds value beyond schema by explaining default model behavior, API key usage (BYO key, direct billing), and context disambiguation purpose.

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 names the resource (LLMs) and action (probe and score visibility). Distinguishes from sibling tools like scan_competitor_ai_presence and ask_pipeworx by focusing on multi-model scoring with a specific metric.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Implicitly suggests when to use versus simpler queries, though could explicitly contrast with single-model tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds valuable behavioral context beyond annotations: it routes to one of 5,334 tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with a single fast call. This is useful supplementary information not available in the annotations.

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

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

The description is long but densely informative, front-loading the 'PREFER OVER WEB SEARCH' directive and using examples effectively. Each sentence serves a distinct purpose: scope, mechanics, trigger phrases, alternatives, and live-news handling. There is minor redundancy between 'START HERE' and earlier guidance, but overall the structure is logical and the length is justified given the tool's breadth.

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?

This is a complex general-purpose query tool with no output schema, so the description must explain return behavior. It does, by mentioning structured answers with stable pipeworx:// citation URIs. It also covers supported domains, example queries, performance characteristics ('one fast call'), and alternatives to sibling tools. Minor gaps like error handling or ambiguous-query behavior exist, but overall the description is highly complete for an agent to use correctly.

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

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

The input schema has 100% description coverage: all parameters are aliases for the single 'question' parameter, each documented as 'Alias for question', and the main parameter is thoroughly described with aliases listed. The description itself does not add parameter-specific semantics beyond the schema, but it does provide example questions that illustrate how to use the parameter. With complete schema coverage, a 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's purpose: it routes factual questions to one of 5,334 tools across 1,393 verified sources and returns structured answers with citations. It explicitly says 'PREFER OVER WEB SEARCH' and specifies the resource (Pipeworx), distinguishing it from 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?

The description provides explicit when-to-use guidance, listing trigger phrases like 'what is', 'look up', and 'current', along with concrete examples. It also gives when-not-to-use and alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also states 'START HERE for most questions' and covers edge cases like breaking news.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: the beta nature, that no candidate is active so behavior matches stable, and that it's a full working router with no degraded fallback. This provides meaningful behavioral disclosure without contradicting annotations.

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

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

The description is front-loaded with 'Beta version of ask_pipeworx' and is information-dense, with each sentence adding context (identity, current state, usage, and reassurance). It is slightly verbose but every sentence earns its place, making it appropriately structured without being wasteful.

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 (beta router, no output schema, multiple aliases), the description covers all essential context: the relationship to ask_pipeworx, current identical behavior, comparison purpose, and full functionality. The mention of 'same response shape' partially addresses return values, and the description is complete enough for an agent to invoke it 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 each alias clearly described. The description adds that the tool has the 'same arguments' as ask_pipeworx, but doesn't provide additional parameter semantics beyond what the schema already offers. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,334 tools and response shape. It distinguishes from the stable ask_pipeworx by being the experimental edge, and from other siblings by highlighting its role as an identical router under test.

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

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

Explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that currently it matches ask_pipeworx exactly, and that results are compared against the stable router, providing clear context for selecting this variant over the stable one.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: the refusal mechanism with specific refusal_reason values, the guarantee to extract only from tool result, the output shape (evidence quote, confidence, fetched_at), and the extra LLM call cost. This goes well beyond annotations, enriching the agent's mental model.

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

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

The description is dense but efficient, front-loaded with the core value proposition, then detailing output and refusal behavior, and ending with usage guidance. It's longer than two sentences, but each sentence adds distinct information (output format, refusal reasons, cost tradeoff). No filler or repetition.

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

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

Given the tool's complexity (5,334 tools, argument filling, extraction, refusal handling) and no output schema, the description compensates fully: it explains return fields, lists all refusal_reason values, and gives concrete use cases. Covers the complete behavioral contract, making the agent confident in invoking it for high-stakes queries.

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 is clear: all parameters are aliases for 'question.' The description reinforces that the tool accepts natural language questions and fills arguments automatically, but it does not add new syntax or format details beyond what the schema already states. Baseline 3 applies because schema does the heavy lifting.

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

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

The description opens with a clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (routes, fetches, extracts using only tool result) and differentiates from sibling ask_pipeworx by emphasizing groundedness and evidence. This is a specific verb+resource+scope, distinguishing it from nearby tools.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and when not to: 'prefer ask_pipeworx for casual lookups.' Also names the alternative (ask_pipeworx) and notes the cost tradeoff. This is textbook 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?

The description extensively covers behavior beyond annotations: resolution, classification, fan-out, response shapes, safety checks (low-confidence matches, closed markets, wide spreads), cancellation rules, and news fallback. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description adds rich context 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?

At over 1000 words, the description is excessively verbose. While front-loaded with purpose, it includes many details (classifiers, fan-out examples, response shapes, edge cases) that could be condensed or moved to an output schema. The length harms readability and quick understanding.

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

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

Despite no output schema, the description covers all important aspects: input formats, response structure, error conditions (low confidence, closed markets, wide spreads), security notes (cancellation rules), and fallback behavior. It is remarkably complete for the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds valuable nuance: explains that 'market' can be slug, URL, or text; clarifies 'depth' enum values (quick vs thorough) and their impact; explains 'include_raw' effects. This adds meaning 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies that it takes a market slug, URL, or question text and returns evidence. This distinguishes it from sibling tools like ask_pipeworx or polymarket_arbitrage.

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

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

Explicit usage scenarios are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly state when NOT to use it or provide alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: sampling frequency (5 minutes), default reading period (~1 hour), and interpretation (lower values mean cleaner electricity). It does not contradict annotations and provides meaningful extras.

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 has some redundancy: 'sampled every 5 minutes per bidding zone' and 'Lower values mean cleaner electricity' appear twice. While the information is front-loaded and clear, it could be more concise without losing meaning.

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 does not explain the return format or provide an example response. The tool is simple (numeric values), so the omission is minor, but for completeness, an example or description of the response structure would be beneficial. Annotations cover safety but not return semantics.

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

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

Schema coverage is 100% with both parameters described. The description adds context beyond schema: it explains the 'area' zones (DK1=west, DK2=east) and clarifies the 'limit' default (12 readings = ~1 hour) and the meaning of values (lower is cleaner). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool returns real-time grid CO2 emission intensity (g CO2/kWh) from Energinet Denmark, with specific sampling frequency (5 minutes), zones (DK1/DK2), and default reading count (12). It effectively distinguishes from sibling tools like spot_prices by specifying the exact data source and metric.

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

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

The description clearly indicates when to use this tool (for real-time CO2 intensity data) and provides context on default behavior. However, it lacks explicit guidance on when not to use it or alternatives for historical or forecast data. Given the tool's simplicity, the guidance is adequate but not comprehensive.

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?

Describes behavior beyond annotations: for 'company' type, pulls latest 10-K data with correct fiscal year handling; for 'drug' type, pulls FAERS counts, etc. States results sorted by primary metric, returns paired data + citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example triggers, then explains behavior. It is dense but informative, with no wasted words. Could be slightly more structured (e.g., separate sections for company vs drug), but it's effective and concise.

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 (two entity types, no output schema), the description covers key aspects: data sources, metrics, sorting, and citation URIs. Missing error case info (e.g., unrecognized ticker) but overall sufficient for an AI agent to use correctly.

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

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

Schema coverage is 100%. Description adds meaning to parameters: explains 'type' enum values (company/drug) and 'values' array with examples (tickers/CIKs for company, drug names). Reinforces constraints (min 2, max 5) but doesn't add entirely novel info beyond schema descriptions.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, with specific example queries ('X vs Y', 'which is bigger', 'rank these companies'). It distinguishes from sibling tools like entity_profile and resolve_entity by emphasizing parallel comparison over sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8-15 sequential lookups. Provides clear when-to-use guidance and implicitly notes alternatives (sequential lookups).

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

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

Though annotations already declare read-only/open-world/idempotent, the description goes far beyond by disclosing account requirements, paid tier for 'thorough', parallel tool routing, the exact response packet (evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[], never-invented policy, contradictions[] scanning, semantic excerpting, hop field, and expected latency. This is substantial addition 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 long but each sentence carries operational or behavioral value—no filler. It front-loads the account requirement and fallback, then moves to purpose and usage. It could be slightly tighter (some depth details mirror the schema) but the complexity of the tool warrants 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?

With no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions) and behavior details like second-hop iteration, semantic excerpting, and latency. It covers both the happy path and limitations (empty gaps for non-structured topics), making it complete for a complex research tool.

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

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

Schema coverage is 100% and already describes both 'question' and 'depth' in detail, establishing a baseline of 3. The description adds extra meaning by explaining that broad/multi-part questions are fine and that 'thorough' requires a paid plan, plus clarifies how depth affects behavior (latency, iteration). It does not repeat the schema's depth enum verbatim, so it earns a 4.

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

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

The description clearly states a specific action (grounded multi-source research) and resource (Pipeworx's 1393 structured data sources), and explicitly distinguishes itself from open-web search and the ask_pipeworx sibling. It is far beyond a tautology.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'), and names alternatives (ask_pipeworx, live news APIs). It also warns against using this for breaking/colloquial news, with a fallback instruction for unsigned-in 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 declare readOnlyHint=true and idempotentHint=true. The description adds value by detailing what the tool returns (top-N tools with names, descriptions, full schemas, and curated examples) and notes that results are 'ready to call directly, no second schema lookup needed.' This goes beyond annotations, though some details like pagination might be missing.

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

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

The description is concise and front-loaded with the core purpose. It covers all essential aspects without unnecessary elaboration, efficiently using every sentence to convey purpose, usage, and output.

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, the description is complete. It explains the return value, usage context, and lists covered data domains. With no output schema, the description adequately informs the agent about what to expect.

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

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

Schema coverage is 100% with well-described parameters. The description adds value by clarifying that the tool accepts multiple aliases for the query (task, q, description, search) and provides examples in the input schema, reducing ambiguity for the agent.

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 'Find tools' and specifies the resource: tools by describing the data or task. It distinguishes itself from sibling tools by indicating it should be called first to discover the option set, making purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not explicitly list when not to use it, but the context is clear enough.

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

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

Beyond annotations (read-only, idempotent), description details fan-out across multiple sources, specific return fields, patents API sunset and soft-fail behavior, and input restrictions. 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?

Front-loaded with examples and clear purpose. Somewhat lengthy but each sentence adds value. Could be slightly trimmed without losing meaning.

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

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

Given no output schema and multiple sources, description thoroughly explains return data (CIK, filings with URIs, fundamentals, patents, news, LEI) and includes constraints (patents soft-fail, name not supported). Complete for its complexity.

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

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

Schema has 100% coverage; description adds context: type limited to company, value must be ticker or zero-padded CIK, names not supported. Provides concrete examples of valid inputs.

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 concrete query examples and clearly states it returns a full cross-source profile of a US public company in one call. It distinguishes from siblings by preferring over chained single-pack lookups.

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

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

Explicitly says when to use (holistic view), when not to use (names not supported), and directs to resolve_entity for names. Also advises preferring over chaining alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, which the description complements by explaining the purpose of deletion (clearing stale or sensitive data). The description adds value beyond the annotations without contradicting them.

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

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

The description is highly concise, consisting of just two sentences. The first sentence states the action, and the second provides usage guidance. There is no redundant or unnecessary 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?

For a simple single-parameter tool with no output schema, the description provides complete context: what it does, when to use it, and how it relates to siblings. No additional information is needed.

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 the parameter (key) with a brief description. The tool description does not add extra detail about the key parameter beyond what the schema provides, so it meets the baseline for full schema coverage.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes this tool from siblings by explicitly pairing it with 'remember' and 'recall', making its role unambiguous.

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

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

The description provides explicit context for when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with sibling tools but does not explicitly state when not to use it or mention alternatives, which would have earned a 5.

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

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

Description discloses read-only, idempotent behavior (fetching, extracting) matching annotations. Adds context about output format and location. 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?

Single paragraph, front-loaded with purpose, each sentence adds value. No unnecessary words or repetition.

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

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

Covers input (URL, max_links), process (fetches, extracts), output format, and practical use cases. No missing information for this simple tool.

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

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

Schema has 100% coverage for both parameters. Description adds no additional meaning beyond schema definitions, meeting baseline for full schema 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?

Description clearly states the tool generates 'llms.txt' files for any URL, specifying the verb 'Generate' and resource 'llms.txt'. It distinguishes from siblings by its unique output format and use case for AI crawlers.

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

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

Provides explicit use cases: indexing client sites, personal projects, auditing competitors. Lacks explicit 'when not to use' or alternative tools, but given no direct sibling tools exist, this is acceptable.

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 and destructiveHint=false, so the agent knows it's a safe read. The description adds return field details, which is useful but not beyond what annotations cover. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, then returns, then usage. Every word earns its place with zero waste.

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 list tool with no output schema, the description provides the return fields and usage context. It covers essential information adequately, though more detail on pagination or rate limits could enhance completeness.

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 parameter 'include_inactive' has a clear description. The tool description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like subscribe/unsubscribe by hinting at its use for reviewing before adding or finding an id to cancel.

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

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

The description explicitly provides usage scenarios: reviewing subscriptions before adding more or finding an id to cancel. While it does not explicitly state when not to use, the context implies alternatives are subscribe/unsubscribe, which is sufficient.

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

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

Discloses rate limit (5 per identifier per day), free usage, no quota impact, and daily review by team. Annotations only indicate non-readonly, non-destructive; description adds actionable constraints 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?

Concise but complete: opens with purpose, lists use cases, provides anti-pattern, and ends with constraints. Every sentence adds value; no fluff.

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

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

Given no output schema, description provides all needed context: what to submit, how to format, limitations, and processing timeline. Complete for an agent to use correctly.

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

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

Description enriches schema: clarifies enum values for 'type', notes context is optional and which fields to use, and provides length/quality guidance for 'message'. Schema coverage is 100%, but description adds practical usage tips.

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

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

Description clearly states the tool sends feedback to Pipeworx team, lists four specific feedback types (bug, feature, data_gap, praise), and distinguishes itself from sibling tools by focusing on user feedback, not data retrieval or analysis.

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

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

Provides clear guidance on when to use (bug, feature, data_gap, praise) and what to avoid (pasting end-user prompts). Does not explicitly list alternative tools, but context makes it unique as a feedback tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable context: self-aggregating, no PII, caching behavior (5min-1h). No contradictions.

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

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

Concise multi-sentence description with bullet-point use cases; no wasted words. Front-loaded with main purpose, then details.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers behavior (caching, data returned, PII handling) and use cases. No gaps.

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

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

Schema coverage is 100% with enum values and description. Description adds context about shorter vs longer windows (e.g., 'surfaces what's hot right now'). This adds value beyond the schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a configurable window. This distinguishes it from sibling tools like 'ask_pipeworx' or 'discover_tools' by being a trending/signal tool.

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

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

Lists three specific use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. While it doesn't explicitly state when not to use it, the guidance is clear and actionable.

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

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

The description discloses detailed behavioral traits including monotonicity checks, partition-sum checks, semantic anchor, partition filter, and fill check. Annotations confirm read-only, idempotent, and non-destructive, and the description adds significant context beyond annotations.

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

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

The description is somewhat long but well-structured with clear sections and key terms. Every sentence adds value, and it is front-loaded with the main purpose. Could be slightly more concise but still effective.

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

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

The description covers the main response fields and processes for all three modes. It lacks some details on error handling and limits, but given the complexity and no output schema, it provides adequate context for proper tool 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 description adds substantial meaning beyond the input schema's parameter descriptions, providing examples, explaining mode behavior, and detailing what each parameter triggers. Schema coverage is 100% but description enriches greatly.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using specific methods (monotonicity violations and partition-sum checks). It is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly explains three usage modes (no args, event, topic) with recommendations and when to use each. It also references sibling tool polymarket_fill_risk for custom sizing, providing clear usage guidance.

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

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

The description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), internal model details, and response structure, adding value beyond annotations which indicate read-only, idempotent, and non-destructive behavior. 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 verbose (over 500 words) and includes extensive internal details that may not be necessary for an agent to invoke the tool correctly. It front-loads the purpose but the technical depth could be condensed.

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 9 parameters, no output schema, and high complexity, the description thoroughly explains the output structure (by_segment, fed_candidates, _diagnostics), edge/ Kelly fields, and filter knobs, making it sufficient for an agent to understand the tool's behavior and results.

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

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

Schema coverage is 100%, so baseline 3. The description does not add significant meaning to parameters beyond what the input schema provides, except for context like 'default 0.5' for min_edge_pp and 'Polymarket has zero trading fees' for slippage_pp, but these are already in the schema descriptions.

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

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

The description starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and states it's built for 'what should I bet on today', providing a clear verb+resource and distinguishing from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description clearly states the intended use case ('what should I bet on today') and explains the output segments and filters, but does not explicitly mention when to avoid using this tool or suggest alternatives among the sibling tools.

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

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

Adds rich behavioral details beyond annotations: decay computed on absolute value, snapshot TTL, gaps mean no scan, response structure. Annotations already indicate read-only, idempotent, non-destructive; description complements strongly.

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

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

Well-structured with sections for purpose, response fields, and limits. Slightly verbose but every sentence adds value. Could be trimmed slightly but still efficient.

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

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

Thorough explanation of response fields (tracked, expired, snapshot_dates) and limits (TTL, gap meaning). No output schema, but description compensates fully. Complete for a read-only monitoring tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces defaults and ranges but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description states it answers 'how long has this edge existed and is it shrinking?' and distinguishes between fresh and persistent edges. Specific verb-resource combination with clear differentiation from sibling tools like polymarket_edges.

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

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

Clear context on why edge persistence matters (a 3-week-old wide edge is different). No explicit when-not-to-use or comparison with siblings, but the purpose implicitly guides 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=true and destructiveHint=false. The description adds behavioral context: it is a simulation/check, not an actual trade; it walks the ladder, returns verdicts (clean|degraded|cannot_fill), and details risks like forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections for single-market and basket modes. Every sentence adds value; no filler. Front-loaded with purpose. Could be slightly more concise, but the level of detail is warranted for a complex tool.

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

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

No output schema exists, but the description fully enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, shares_filled, verdict, per-leg detail, thin_legs, forced_directional_risk). It covers behavior for all parameters and modes, making it complete for an agent to understand tool behavior and outputs.

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

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

Schema description coverage is 100%, baseline 3. However, the description adds significant context: explains mutual exclusivity of market/event, default side logic in each mode, and different interpretation of size_usd for single-market vs basket (max spend vs target proceeds vs settlement notional). 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?

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about the verb (checks, evaluates) and the resource (order-book depth), and it differentiates from siblings like polymarket_arbitrage and polymarket_edges by noting it should be used before them.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about partial basket fills converting arb into unhedged directional positions, providing clear when-to-use and why-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: compatibility warnings, temporal alignment checks, skipped comparisons based on metric type/inequality, and the note that real spreads are rarer than the shortcut list suggests. No contradictions with annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is thorough but not overly verbose; every sentence adds necessary information. Minor verbosity in some parenthetical asides prevents a top score.

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

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

Despite lacking an output schema, the description fully explains the response structure (leg prices, spread, safety fields). It covers edge cases (compatibility warnings, mismatched bet shapes, temporal gaps) and provides examples, making it complete for an agent to understand and use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the exact topic shortcuts, providing examples of explicit tickers, and explaining how parameters interact (e.g., topic overridden by explicit tickers). This exceeds simple schema documentation.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit tickers) and distinguishes it from siblings by emphasizing its cross-venue nature, which is unique among the listed 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 clear guidance on when to use each mode and includes safety warnings about compatibility and temporal alignment. It does not explicitly compare to the sibling 'polymarket_arbitrage' but still offers sufficient context for appropriate 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 readOnly, idempotent, non-destructive behavior. The description adds: 'Returns the raw records array for the dataset. Keyless official open data.' This tells agents it returns raw data and requires no authentication, which is useful context beyond annotations.

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

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

The description is very concise: three sentences plus examples. It front-loads the core purpose ('generic escape hatch') and lists examples immediately. No unnecessary words.

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

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

Given 6 parameters, no output schema, and the tool's generic nature, the description covers the essential behavior (returns raw records, keyless open data). The examples help, but missing details like pagination limits or error behavior. Still, it's largely adequate for an agent to use correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds value through concrete examples showing typical parameter combinations, but does not explain nuances like how filter or sort work 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 is a generic escape hatch for ~100 Energi Data Service datasets, with concrete examples. It distinguishes itself from specialized sibling tools like spot_prices and co2_intensity by implying it covers all other datasets.

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

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

The description calls it a 'Generic escape hatch' which suggests using it when dedicated tools aren't available, but it does not explicitly state when to use or avoid it versus siblings. The examples hint at usage patterns but lack explicit 'when to use' guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false; description adds value by explaining the scoping mechanism and the behavior of omitting the key to list all keys. No contradictions.

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

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

Two sentences pack all essential information: action, optional behavior, use cases, scoping, and pairing. No wasted words, front-loaded with the core 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 simple read-only tool with one optional parameter, the description is thorough. It covers purpose, usage, scope, and relationships to sibling tools. Return value format is not specified but understood from 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?

The single optional parameter is fully described in the schema (100% coverage). The description adds the critical detail that omitting the key lists all saved keys, which is not in the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with a specific verb (retrieve/list) and resource (saved values). It distinguishes from siblings by mentioning remember and forget 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?

Provides clear context for when to use (look up previously stored context) and mentions scoping to an identifier. Does not explicitly state when not to use or exclude alternatives, but pairing with remember/forget is implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the return fields (source, citation_uri, raw event payload) and the behavior of mark_read:true (flags events read so next call shows only newer ones), which is not evident from annotations alone.

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

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

The description is a single, well-structured paragraph of 4 sentences. It is front-loaded with the purpose, then details parameters and behavior, and ends with an alternative usage note. Every sentence adds value without redundancy.

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

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

With no output schema, the description compensates by listing the fields in returned events (source, citation_uri, raw event payload). It also explains polling suitability, the alternative REST endpoint, and the effect of mark_read on pagination. For a read-only list tool with 5 optional params, this is complete and actionable.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds beyond the schema: it gives an example for type filter ('sec_8k'), explains the side effect of mark_read, and clarifies that since is an ISO timestamp for comparing fired_at. This provides useful context beyond the raw property descriptions.

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

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

The description starts with a specific verb-resource pair: 'Pull fired events from your subscription feed.' It clearly states what the tool does and distinguishes it from siblings like list_subscriptions or subscribe by focusing on alerts and their content (source, citation_uri, payload).

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

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

The description explains when to use this tool vs an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' It also describes the effect of mark_read:true on subsequent calls, providing clear context. However, no explicit when-not-to-use statements are present.

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

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

Annotations already indicate safe read-only operation; description adds valuable behavioral details such as fan-out to multiple sources, rate-limit handling via fallback, and structural output (changes grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

Description is dense but each sentence earns its place. Front-loaded with example queries. Slightly long but efficient for the breadth of information conveyed.

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

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

Given the tool's complexity (multiple sources, fallback, error handling), the description covers all necessary aspects: inputs, behavior, output structure, and alternative tool. No output schema but return format is described.

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

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

Schema covers 100% of parameters, but description adds meaningful context: explains that 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' is limited to 'company'. This goes beyond schema descriptions.

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

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

The description clearly states it's a 'change feed for a company' with specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from sibling tool 'entity_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?

Provides explicit when-to-use examples ('What's new with X', 'latest on Y') and when-not-to-use ('Use entity_profile instead for static profile regardless of window'). Also explains fallback behavior and soft-fail conditions.

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 key behavioral traits beyond annotations: key-value scoping by identifier, persistence duration (authenticated persistent, anonymous 24h), and non-destructive nature. 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 articulate and front-loaded with the primary action, but every sentence earns its place. Slightly verbose but maintains clarity.

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

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

Given no output schema and the simple key-value pattern, the description is complete enough. It explains the storage scope, persistence, and how to pair with sibling tools.

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

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

Schema has 100% coverage with descriptions for both key and value. The description adds context about the key-value pair and gives concrete examples, providing added value beyond the schema.

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

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

The description clearly states the tool's purpose: saving data for reuse across conversations or sessions. It uses a specific verb+resource ('Save data... reuse'), and distinguishes itself from sibling tools like recall and forget.

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

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

The description explicitly says when to use (when discovering something worth carrying forward) and pairs with recall for retrieval and forget for deletion, providing clear context and alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it notes that each call cascades through several endpoints and replaces 2-3 manual lookups. This goes beyond the annotations but does not describe rate limits or authentication needs.

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 yet information-dense, with a clear front-loaded structure. Every sentence adds value: examples, usage guidance, supported types with return details, and an efficiency claim. No wasted words.

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

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

Given the tool's simplicity (2 parameters, no output schema, comprehensive annotations), the description fully covers the return values and behavior for each entity type. It provides enough detail for an agent to confidently use the tool 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?

Schema coverage is 100%, providing a baseline of 3. The description significantly enriches both parameters: for 'type' it explains the enum values and their meanings, and for 'value' it gives concrete examples (e.g., ticker, CIK, name for company; brand/generic for drug) and describes the return format for each type.

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

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

The description clearly states the tool's purpose with specific examples like 'What's the ticker for…' and explicitly says it resolves names to canonical identifiers. It distinguishes from siblings by emphasizing that this tool provides IDs required by other tools, which is a unique role.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. While it does not explicitly state when-not-to-use or name alternative tools, the context implies that if an ID is already available, this tool is not needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial context: it explains the internal process (calling ai_visibility_check per entity), ranking by score, and output details (ranked list with score, confidence, signal density). 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 two sentences plus a parenthetical example, all front-loaded with the primary action. Every sentence adds unique value without redundancy, making it highly concise and well-structured.

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

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

Given the tool's complexity (multi-entity comparison, ranking), the description is complete. Schema covers all parameters, annotations cover safety, and description explains the process and return format (ranked list with score, confidence, signal density) despite no output schema. An agent can fully understand when and how to use it.

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: it specifies that the first entity in 'entities' is treated as the 'subject' and the rest as competitors, and explains 'context' as disambiguation for common names. This elevates the score to 4.

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

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

The description clearly defines the tool as comparing AI visibility across multiple entities side-by-side, using specific verbs (compare, probe) and resource (AI visibility). It distinguishes itself from sibling 'ai_visibility_check' by focusing on multi-entity ranking.

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

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

The description explicitly states use for competitive AI-marketing audits and gives a concrete example question. It implies single-entity checks should use 'ai_visibility_check', but does not explicitly list when-not-to-use or alternative tools beyond the implicit contrast.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and the sources_failed field will list timeouts. No contradictions.

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

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

The description is front-loaded with the core purpose and structured to cover return details, limitations, and alternative usage. It is slightly verbose but each sentence provides necessary 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 adequately details the return summary fields (is_latest, license, advisory_count, size info, etc.), explains partial failure behavior, and notes ecosystem scope and alternatives, making it complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages ('@types/node') are accepted and that omitting version defaults to latest, which clarifies the schema further.

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

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

The description starts with a clear composite purpose: 'should I add this npm package to my project' check. It explicitly lists the data sources (deps.dev, bundlephobia) and types of information (license, advisories, package size, ESM support), which distinguishes 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 tells when to use the tool: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the ecosystem limitation and mentions alternative tools/bare queries for other ecosystems.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds significant behavioral details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and that passages include offsets for verification. This goes well 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 concise (5 sentences), front-loaded with the main purpose, and every sentence adds unique information about usage, behavior, or integration. No wasted words.

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

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

Despite no output schema, the description explains return values (top-N passages with character offsets and similarity scores). It covers capabilities, limits (200K chars, truncation), and integration context. For a search tool with 3 parameters, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'text' is document text with max length, 'query' is natural-language with examples, and 'limit' is max passages with default. It clarifies the purpose 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 performs semantic search inside a fetched record with specific verbs and resources. It distinguishes itself from siblings by mentioning it pairs with ask_pipeworx_grounded and is for searching within an already-fetched record, unlike other tools that may fetch or summarize.

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

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

It explicitly says when to use ('Use when the record is too big to cram into the prompt'). It explains benefits (saves context, returns passages with offsets) and notes it pairs with ask_pipeworx_grounded. However, it does not explicitly list alternatives or when not to use, though sibling tools are provided separately.

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 that the data is 'Keyless official open data', but does not disclose rate limits or pagination behavior, relying on annotations.

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

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

Three sentences, front-loaded with main purpose, no fluff. Efficiently conveys essential information.

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

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

With four well-described parameters and rich annotations, the description provides sufficient context for using the tool. No output schema, but the response is simple hourly prices, so no additional explanation needed.

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

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

Schema coverage is 100% with each parameter described. The description adds useful context about omitting 'area' for all zones and the default limit behavior, enhancing understanding beyond the schema.

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

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

The description clearly states it retrieves day-ahead electricity spot prices from Energi Data Service, specifying bidding zones, currencies, and hourly granularity, which distinguishes it from sibling tools like co2_intensity or query_dataset.

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 examples and mentions options like area and limit, but does not explicitly guide when to use this tool vs siblings. The context is clear but lacks explicit 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 discloses several behavioral traits not covered by annotations: authentication requirements, supported subscription types with specific parameters, delivery channel details (email templating, SMS limits, webhook HMAC signing and auto-disable after 10 failures). Annotations indicate idempotentHint=true, but the description does not clarify idempotency behavior, which is a minor gap.

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

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

The description is well-structured and front-loaded with the core action, then return value, prerequisites, types, and delivery channels. Every sentence adds necessary information. Though detailed, it remains concise and avoids redundancy.

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

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

Given the tool's complexity (3 parameters with nested objects, no output schema), the description is highly complete. It covers all subscription types, delivery channels, prerequisites, and constraints (e.g., SMS phone verification, email validation, webhook signing). It addresses return value and typical usage scenarios.

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

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

The input schema has 100% description coverage, but the description adds significant meaning beyond the schema. It explains each enum value for 'type' with real-world examples, provides detailed format for 'params' per type, and elaborates on 'delivery' options including verification and signing details. This greatly aids correct parameter construction.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (Create), the resource (subscription to live-data event stream), and mentions it returns a new subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides context for use: requires a Pipeworx OAuth account, and notes that anonymous/BYO cannot persist subscriptions. However, it does not explicitly guide when to use this tool vs. alternatives like list_subscriptions or unsubscribe. The usage is implied but not directly contrasted.

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 and destructiveHint=false. Description adds further behavioral details: returns category-bucketed examples with exact tool+argument shapes from a live catalog. No contradictions.

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

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

Description is somewhat lengthy but packed with useful information. It front-loads alternative phrasings for user intent, which aids recognition.

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 large sibling tool set, this description perfectly positions the tool as the first entry point. It explains the output (example questions with tool shapes) and parameter usage, compensating 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%, but description adds meaning by listing specific focus areas (finance, pharma, etc.) and clarifying that omitting 'topic' gives a cross-category spread.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and identifies the resource ('onboarding entry point for an agent'). It distinguishes from siblings like 'ask_pipeworx' by stating it teaches how to call meta-tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains optional 'topic' parameter for focus.

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 that the row is deactivated, not deleted, and explains why (historical events stay available), adding context beyond annotations. No contradiction with annotations.

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

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

Two sentences with no wasted words. Front-loaded with the core action. Efficient and well-structured.

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

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

For a single-parameter tool with no output schema, the description fully covers behavior, constraints, and post-effect. An agent can confidently use this tool.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. Tool description adds minimal extra meaning ('by id'), but baseline of 3 is appropriate as schema already handles parameter semantics.

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

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

Clearly states the action ('Cancel a subscription by id') with a specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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 key usage constraint: ownership enforcement ('you can only cancel your own subscriptions'). Does not explicitly mention when not to use or alternatives, but the constraint is sufficient for 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, aligning with the description's non-destructive nature. The description adds behavioral context: it uses different verification pipelines (structured vs. grounded), performs exact percent-delta math for financial claims, and replaces 4–6 sequential calls. No annotation contradiction.

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

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

The description is a single paragraph but well-structured: it starts with common use-case phrases, states the core purpose, details the two verification paths, and explains the return values. Every sentence is informative, though it could be slightly more concise by removing some redundancy in the phrasing.

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

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

Given the tool's complexity (two pipelines, no output schema), the description adequately covers the return format (verdict, actual value with citation, reasoning) and the routing logic. It mentions the verdict types and the evidence format, but does not detail the exact citation structure or edge cases. Still, it is sufficiently complete 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% with descriptions for both parameters. The tool description adds value by providing examples for the 'claim' parameter ('Apple's FY2024 revenue was $400 billion') and by explaining the 'tolerance_pct' parameter's default behavior and recommended use cases (e.g., 1–2 for hallucination detection). This goes beyond the schema's minimal descriptions.

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

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

The description explicitly states the tool performs fact-checking of natural-language claims against authoritative sources, with specific examples of input phrasing. It distinguishes between company-financial claims (using SEC EDGAR path) and other claims (grounded pipeline), and lists the verdict types returned. This clearly differentiates it from sibling tools like ask_pipeworx or 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?

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the fallback routing for financial vs. other claims, providing context for when each path is used. It does not explicitly mention when not to use the tool, but the guidance is clear enough to decide.

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