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 establish read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it routes to sub-tools, fills arguments automatically, returns structured answers, and includes stable pipeworx:// citation URIs. It does not disclose potential latency, cost, or failure modes, but the key invocation-relevant behavior is covered.

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 most important guidance ('PREFER OVER WEB SEARCH', 'START HERE') and covers a lot of ground efficiently. However, it is somewhat verbose, with an extended list of examples and source categories that partially duplicates what the schema examples already provide.

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

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

For a complex router-style tool with no output schema, the description is largely complete: it covers when to use it, what it does, what output to expect, and how it relates to sibling tools. It could mention limitations or edge cases (e.g., ambiguous queries, non-factual questions), but nothing essential for selecting and invoking it is missing.

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

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

Schema coverage is 100%, and the schema already describes the only required parameter 'question' and its aliases. The description adds little parameter-level detail, but the schema carries the burden adequately, so the baseline score of 3 is appropriate.

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

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

The description states a specific, distinctive behavior: routing questions to one of 5,798 tools across verified sources and returning structured answers with citation URIs. It positions itself as the default entry point and explicitly distinguishes itself from ask_pipeworx_grounded, ask_pipeworx_beta, 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 gives explicit when-to-use guidance: prefer over web search for factual, current, or historical data questions, with trigger phrases and concrete examples. It also names alternatives and exactly when to step up to them ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research').

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

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

The annotations already indicate safety (readOnly, non-destructive, idempotent), but the description adds crucial context: it is an experimental live router with candidate improvements enabled during tests, currently no candidate is active, and it has no fallback—it is a full working router. This goes well beyond the annotations and conveys the dynamic behavioral nature.

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

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

The description is detailed but every sentence adds value: beta status, identical capability, experimental state, usage instruction, and current status. It could be tightened slightly, but it is well-organized and front-loads the most important distinction (beta vs stable).

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

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

For a router with no output schema, the description provides all necessary context: identical to ask_pipeworx, experimental differences, active-candidate status, and the fact that it is fully functional. An agent knows exactly what to expect and how 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 description coverage is 100%—all parameters are aliases for 'question' and are fully documented. The description states 'same arguments' but adds no new parameter-level detail, which is acceptable given the schema already carries the semantic weight.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx with an explicit resource: a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by its experimental routing improvements, making its function 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 gives explicit guidance on when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router and notes the current inactive state, leaving no ambiguity about the choice between this and ask_pipeworx.

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 say readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail beyond those hints: the grounding mechanism, the exact success response shape, the enumerated refusal_reason values, and the extra LLM call cost. This is exactly the kind of behavioral context annotations alone do not convey.

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

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

The description is compact for the complexity it covers, front-loads the core differentiator ('hallucination-resistant answer mode for high-stakes reads'), and every sentence contributes: behavior, refusal semantics, use cases, and routing preference. No filler or redundant restatement of the title.

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 having no output schema, the description explicitly documents both success and refusal return shapes, including refusal reason enumerations. It also provides sufficient context for high-stakes read scenarios and sibling routing. An agent has everything needed to decide when to call this tool and to interpret its response.

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

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

The input schema already documents question and its aliases with 100% description coverage, so the description does not need to re-explain parameters. The description references the question indirectly through routing and answer extraction but adds no new parameter-level meaning. Baseline 3 is appropriate because the schema carries the full parameter burden.

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

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

The description states a specific function: a hallucination-resistant, grounded answer mode that extracts answers only from tool results and returns explicit refusals when data is insufficient. It clearly distinguishes itself from ask_pipeworx by positioning itself as the high-stakes, citation-worthy variant, so an agent can disambiguate it from siblings without inspecting schemas.

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

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

The description explicitly tells the agent when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), when not to use it ('prefer ask_pipeworx for casual lookups'), and notes the trade-off ('costs one extra LLM call'). This is direct, actionable usage guidance that names the alternative.

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

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

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavior: account and plan requirements, parallel routing, gaps[] for unanswered facets, contradictions[] in standard/thorough modes, resolvable citation URIs, semantic excerpting, and latency expectations. It even states findings are 'never invented,' which is critical grounding context. No contradiction with annotations.

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

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

The description is long but information-dense and front-loaded with the most critical operational facts (account requirement, fallback tool) before the detailed mechanics. There is minor redundancy in the depth-related details that also appear in the schema, but the added nuance justifies most of the length. Slightly verbose, yet each sentence earns its place for such 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?

With no output schema, the description carries the full burden of explaining return semantics, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers latency, depth variants, and sourcing scope, leaving an agent with everything needed to select and invoke the tool correctly.

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

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

Though the schema already covers both parameters (100% coverage), the description adds real value: it explains the 'depth' tiers with behavioral differences (single hop vs gap recovery vs lead chasing), paid-plan implications, and that 'question' supports broad/multi-part natural language. This goes beyond the schema's enum description and helps an agent choose the right depth.

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 precise verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and explains it decomposes questions into facets, runs tools in parallel, and returns a findings packet. It explicitly contrasts itself with open-web search and points to ask_pipeworx for single lookups, making its niche unmistakable among siblings.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also gives account-tier conditions ('if you are not signed in, use ask_pipeworx') and details depth options, so an agent can decide both whether and how to invoke the tool.

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

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

Annotations already 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 the readOnly/idempotent/openWorld annotations, the description discloses parallel fan-out, GDELT-to-GNews fallback, the meaning of sources_used/sources_failed, expected empty FDA sections for small-molecule companies, and resolved:false outputs for private companies. There is 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 requests and a one-line purpose, and nearly every sentence adds useful operational detail. But the middle return-field listing is long, semicolon-dense, and slightly telegraphic in spots such as 'patents (USPTO...)'.

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 well by enumerating most returned sections, source fallbacks, and edge cases. A few sections such as patents and news mentions remain underspecified, so it is very complete but not fully exhaustive.

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 already documents that type values are interchangeable and that value accepts ticker, zero-padded CIK, or company name. The description mostly repeats those facts with the same examples, adding no new parameter-level meaning.

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

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

The description states a specific deliverable: 'full cross-source profile of a US public company in ONE parallel call,' backed by example user intents. It distinguishes the tool from single-source or lookup-only siblings by emphasizing the holistic, cross-source nature.

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

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

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear selection rule. It also states the accepted input forms and the behavior for private companies, so an agent knows when the tool is appropriate.

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?

Annotations are all false, providing no safety signals, so the description carries the full burden. It discloses key behavioral details: 'Filing without an account returns a claim_token; pass it back later...' and 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also explains the feedback workflow (digests, roadmap impact) with no hidden side effects, making it highly transparent.

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

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

The description is longer than average but every sentence earns its place: purpose, usage conditions, scope restriction, disambiguation, claim_token workflow, rate limits, and cost. It is front-loaded with the core purpose and flows logically through usage, exclusions, and mechanics. No redundancy or filler.

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

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

No output schema exists, so the description compensates by explaining the return behavior (claim_token and how to use it for follow-up). It covers all parameter semantics, usage scope, rate limits, and the feedback lifecycle. For a tool with this complexity (4 params, nested contexts, non-trivial workflow), the description is thorough and leaves no critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the claim_token interaction ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by giving message guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). While not a huge delta, these practical instructions enhance parameter understanding.

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

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

The description opens with a specific, direct statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the action (sending feedback) and the resource (Pipeworx team/tools). It also distinguishes itself from sibling tools like ask_pipeworx by focusing solely on feedback about the tools themselves.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This fully equips the agent to decide when to invoke this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. 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 mark this as read-only and non-destructive, and the description adds extensive behavioral detail beyond that: identical token-overlap matcher in both modes, compatibility_warning and compatibility_codes semantics, fee disclosure, unclassified-leg exclusion, and skipped comparison counters. It also clarifies that temporal_alignment null means 'not computed,' not 'aligned.' No contradiction with annotations exists.

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 structured and front-loaded with the core purpose, then modes, response shape, safety fields, and caveats. Every clause carries operational meaning, though the sheer volume of warnings and code enumerations makes it feel heavier than ideal. It could be tightened, but it is not padded.

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 present, the description fully compensates by explaining the response fields: per-venue prices, top_spreads_pp, flags[], skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. For a complex cross-venue comparison tool, the operational and interpretative guidance is complete enough for an agent to invoke it and understand 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 the baseline is 3, but the description adds meaningful interpretation: topic maps to 10 named macros, explicit ticker/slug override the topic-mapped side, and both modes run the same matcher with the same disclosures. This goes beyond the schema's terse descriptions, especially in clarifying the relationship between the three parameters.

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

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

The description opens with a precise statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explicitly contrasts with same-venue tools like polymarket_arbitrage by framing the delta as a venue-participant signal. The two-mode structure (topic vs explicit) further specifies exactly what resource the tool operates on.

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 explains when to use each mode: topic shortcuts for pre-mapped macros, explicit tickers/slugs for custom pairings, and it warns that most pre-mapped topics are not currently tradeable. It does not explicitly name sibling alternatives or state when not to use the tool, but the mode-level guidance and caveats give an agent strong contextual direction.

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 provide readOnly, openWorld, idempotent, and destructiveHint=false, but the description adds substantial behavioral detail: graceful degradation when GLEIF/OpenFIGI is unavailable, returning figi_candidates on ambiguous matches rather than asserting, explicitly listing unresolved identifiers, and noting that internal cascading replaces several manual lookups. This exceeds what annotations convey.

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

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

The description is long but front-loaded with immediately useful examples and the core use instruction. Each paragraph earns its place by adding edge-case behavior, though some editorial commentary (e.g., 'which is the correct answer to...') could be trimmed without losing needed information.

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

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

Given the tool's complexity, two entity types, input variations, multiple identifier sources, and ambiguity handling, the description is remarkably complete. It explains matching behavior, failure modes, unresolved identifiers, source labeling, and return content for drug lookups, compensating well for the absence 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 the description still adds significant meaning beyond the schema. It gives concrete value examples, explains exactly how to phrase bond issuer names versus full noun phrases, enumerates accepted company inputs (ticker, CIK, ISIN, name), and clarifies drug value semantics. This is a model of parameter clarification.

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

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

The description opens with concrete query examples, then states the precise function: resolving user-spoken names to canonical/official identifiers that other tools require as input. This clearly distinguishes resolve_entity as the identifier-lookup tool among its siblings, such as entity_profile or compare_entities.

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

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

The description gives strong usage context: 'Use FIRST whenever you have a name but need an ID,' and it details which entity types and input forms are accepted. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 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?

Adds critical behavioral context beyond annotations: explains the two distinct verification paths, the exact verdict list, citation behavior, and the semantic distinction between could_not_verify and unsupported. No contradiction with readOnly/openWorld/idempotent annotations.

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

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

Well-structured, front-loaded with purpose, uses examples inline, and every sentence adds value (trigger phrases, dual-path logic, caller warning, replaced-call count). Length is justified by complexity.

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

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

No output schema exists, but description enumerates all possible verdicts, explains error handling, and covers both financial and non-financial claim routes, making it complete for an agent to choose and invoke safely.

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

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

Schema already documents both params, but description adds meaning by explaining tolerance_pct overrides claim-implied tolerance, provides a use case (1–2 for hallucination detection), and notes default cap of 5.

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 trigger phrases and explicitly states it performs natural-language claim verification against authoritative sources, clearly distinguishing from sibling tools by its verdict-based output and dual-path handling (SEC EDGAR for company-financials, grounded pipeline for others).

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides exclusions by explaining could_not_verify vs unsupported, plus notes it replaces 4–6 sequential calls, giving clear 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.