Energy Charts

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 valuable behavioral context: the default model is free, _apiKey triggers paid Anthropic calls, and the return structure includes per-model fields like score, confidence, signals, and raw_response plus a combined view. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph of four sentences. It front-loads the main action and returns structure, with 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?

The description covers the tool's purpose, usage, parameters, and return structure adequately. However, it does not mention error handling, rate limits, or what happens if the entity is not found. Given the annotations and schema, the description is largely complete but could be slightly more thorough.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about the default model and when _apiKey is needed, but this is marginal beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('probe one or more LLMs'), the resource ('what they know about a business/brand/product/topic'), and the output ('score visibility 0-100 per model'). It distinguishes from sibling tools by being specifically about AI visibility checks, not generic Q&A or research.

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

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

The description provides clear context on when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic integration. However, it does not explicitly state when NOT to use it or compare with similar tools like 'deep_research' or 'scan_competitor_ai_presence'.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful context: it routes, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. This goes beyond annotations but doesn't disclose potential failure modes or ambiguity handling.

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 most critical guidance (prefer over web search, domains). It includes examples and alternative tool pointers, with each sentence serving a purpose. Though a bit long, it remains readable and scannable.

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

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

For a complex routing tool with no output schema, the description provides sufficient context: what it returns (structured answer with citations), when to use it, and how it differs from alternatives. It doesn't detail the exact response structure or edge cases, but the selection context is well covered.

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

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

Schema coverage is 100% with descriptions for all parameters, including aliases. The tool description complements this by providing concrete examples of valid questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that clarify expected natural-language input. It doesn't repeat schema details but adds illustrative context.

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

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

The description clearly states the tool's function: it routes factual questions to the right underlying tool among 5,529 tools across 1455 sources and returns structured answers with citations. It explicitly distinguishes from sibling tools like ask_pipeworx_grounded and deep_research, making its role unique.

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

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

Provides explicit when-to-use guidance (prefer over web search, default entry point for factual questions) and when-not-to-use alternatives (step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad/multi-part questions). Also lists trigger phrases and examples, giving clear situational 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?

Beyond the readOnly/idempotent annotations, the description reveals behavioral state: candidate routing improvements may be live, no candidate is currently active (retired 2026-07-26), and it is a full working router rather than a fallback. This prevents misinterpretation and adds valuable context not present in 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 information-dense and front-loaded with the core identity, but slightly redundant ('identical', 'same', 'exactly' repeated) and includes a specific retirement date that may be unnecessary. Still, each sentence contributes useful context and the structure is logical.

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 a simple one-required-parameter schema, rich annotations, and no output schema, the description supplies all needed context: what the tool is, its current experimental state, how to use it, and that it returns the same response shape as ask_pipeworx. Agents can correctly select and invoke this tool.

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

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

The input schema fully describes all parameters, covering question and five aliases at 100% coverage. The description only says 'same arguments' without adding new semantics, so the baseline of 3 applies since schema does the heavy lifting.

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

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

The description clearly states this is a 'Beta version of ask_pipeworx: identical universal router' with the same 5,529 tools, arguments, and response shape. It distinguishes itself from stable ask_pipeworx by being the experimental edge and explicitly notes current behavior matches ask_pipeworx exactly, making the 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?

It gives explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not mention when not to use it or alternatives like ask_pipeworx_grounded, but the primary condition 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses refusal behavior with specific refusal_reason values, the evidence/verbatim quote return, and the extra LLM call cost. It also explains the routing and extraction process, adding substantial behavioral context not captured in 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?

Although longer than typical, the description is structured with success/error formats and usage cases. Every section adds operational value, and the front-loaded opening sentence immediately conveys the tool's core purpose. Slightly dense but not wasteful.

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

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

For a tool with no output schema, the description thoroughly explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), all error modes, and cost trade-offs. This makes it fully contextually complete for an agent to decide whether to use it and what to expect.

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

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

The schema already covers all six parameters (all aliases for 'question') with descriptions, achieving 100% coverage. The tool description does not add param-specific semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' that routes through the same infrastructure as ask_pipeworx but adds grounded extraction. This specific verb+resource combination distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta.

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 an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance relative to its sibling. This is exactly the kind of alternative specification the dimension asks for.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes well beyond, detailing market resolution, classification, fan-out logic, response shapes, edge cases (low-confidence, closed markets, wide spreads), and cancellation rules. This is 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 front-loaded with the core purpose and then expands into detailed, valuable information. While lengthy, every section adds necessary context for proper tool use. It could be slightly more concise, but the structure is logical and informative.

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 (fan-out, classifiers, response shapes, error handling, cancellation rules) and lack of output schema, the description covers all essential aspects. It details what to expect in the response, how to handle confidence levels, and potential issues, ensuring 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% with descriptions for all three parameters. The description adds further nuance: market accepts slug/URL/question text; depth explains quick vs thorough; include_raw explains when true is useful. This significantly aids correct invocation.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the action and resource with examples. However, it does not explicitly differentiate from sibling tools like ask_pipeworx or deep_research, though the purpose is evident.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides multiple usage examples and classifier types. It lacks explicit 'when not to use' instructions, but the context is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds specific data sources and fields per type, handling of off-calendar fiscal years, sorting by primary metric, and inclusion of 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 well-structured, front-loaded with common triggers, then core purpose, then detailed behavior. Every sentence adds value; no redundancy or 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?

With no output schema, the description fully explains what the tool returns (paired data + citation URIs), covers both entity types, and provides sufficient detail for an agent to invoke correctly and understand the output.

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. Description adds meaning beyond schema by explaining the enum values (company vs drug) with details on data pulled, and clarifies that values should be tickers/CIKs for company and drug names with examples. Adds substantial value.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools like entity_profile by explicitly preferring this over sequential single-entity 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?

Provides explicit trigger phrases, states when to use (comparing entities), and advises against sequential lookups. Also specifies constraints (2-5 entities) and notes it replaces 8-15 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?

Discloses account/paywall requirements, parallel decomposition, findings packet structure, gaps[] behavior, never-invents guarantee, semantic excerpting, latency, and hop/citation semantics. Annotations already declare read-only/idempotent, and the description adds substantial context 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 dense and information-rich, but it is a single long run-on paragraph mixing account/tier, usage, technical output format, and latency. Each sentence adds value, but structure could be better with headings or shorter sentences; still appropriately sized 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?

With no output schema, the description fully specifies the return packet (evidence+confidence+source+fetched_at+citation, gaps[], contradictions[], hop, citation_uri) and operational behavior (excerpting, latency, tiers, alternatives), making the tool's behavior and expectations 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, but the description materially enriches parameter meaning: it explains what each depth value does (gap recovery, contradiction scan, follow-up hop), what kind of question is appropriate, and what findings contain, including citation resolvability. Adds far more semantics than the schema alone.

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

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

The description identifies a specific verb+resource ('grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources'), explains decomposition and parallel routing, and explicitly contrasts with ask_pipeworx and open-web search, distinguishing it from 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?

Explicit usage guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and preference for ask_pipeworx for breaking/current news. Depth-tier behavior and account requirements are also clearly stated.

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

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

Description adds that results include full schemas and are ready to call directly, beyond annotations like readOnlyHint. 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 appropriately sized, front-loaded with purpose, but includes a list of domains that could be trimmed. 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?

Since there is no output schema, the description adequately explains the return value (tool names, descriptions, schemas) and behavior (no second lookup 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%, so baseline 3. The description does not add extra meaning beyond what the schema already provides for parameters.

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

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

The description clearly states 'Find tools by describing the data or task' and lists numerous domains, distinguishing this discovery tool from sibling tools that perform specific tasks.

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 'Call this FIRST when you have many tools available and want to see the option set', but does not provide explicit 'when not to use' or alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by specifying the return structure ({unix_seconds, price, unit}), that the array is timestamp-aligned, and the unit (EUR/MWh). This provides context beyond annotations without contradiction.

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

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

Two sentences, no filler. The first sentence states purpose and scope; the second explains the return format. Every part earns its place.

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

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

The tool is simple and read-only. Parameters are fully described in the schema. The description explains the output structure despite no output schema, covering the essential return fields. No gaps are evident for this use case.

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 applies. The description does not add detail beyond the schema's parameter descriptions (e.g., bzn as bidding-zone code, dates optional). It mentions 'over a date range' which loosely connects to start/end, but doesn't enhance semantic understanding of the parameters.

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

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

The description clearly states the tool retrieves day-ahead spot electricity prices for a bidding zone over a date range. It specifies the resource (electricity prices), verb (returns), and scope (bidding zone, date range). This distinguishes it from sibling tools like installed_power or renewable_share, which deal with capacity or generation.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The context is implied by the name and description, but unlike the calibration example with get_calls, no alternative tool is named. The tool is clearly for price data, but agents might benefit from knowing that other power tools exist for different purposes.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds context like patents soft-failing after May 2025 and news fallback from GDELT to GNews. This goes beyond annotations without contradicting them.

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

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

The description is relatively long but every line adds value: usage examples, data source enumeration, return fields, and limitations. It is well-structured with clear sections and no redundant information, earning a high score for being informative without being verbose.

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

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

Given the tool's complexity (multiple data sources, fallbacks, return structure), the description is remarkably complete. It lists all returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), addresses edge cases (patents sunset, name not supported), and since there is no output schema, the description serves as the sole documentation of 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% with clear descriptions for both parameters. The description further clarifies the value parameter with examples (ticker or zero-padded CIK) and repeats the name limitation, adding practical guidance 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 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X' and 'research Acme', distinguishing it from chaining multiple single-source lookups. Sibling tools like deep_research and compare_entities are alternatives, but the description explicitly frames its niche.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use: 'Names not supported (use resolve_entity first if you only have a name).' Provides clear when-to-use and when-not-to-use with alternatives.

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

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

Annotations already indicate destructiveHint=true, and description confirms with 'delete'. Additionally, it reveals purpose of clearing sensitive data, adding context beyond annotations without contradiction.

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

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

Two concise sentences, front-loaded with action, no superfluous text. Every sentence adds value.

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

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

For a simple tool with 1 param, no output schema, and annotations covering destructiveness, the description fully satisfies contextual needs including usage guidelines and pairing.

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 param description 'Memory key to delete'. Description adds no extra semantics beyond the schema, meeting baseline but not exceeding.

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 deletes a memory by key, using strong verb 'Delete' and specific resource 'memory'. It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clearing sensitive data. Also instructs to pair with remember and recall, guiding tool selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: it fetches the page, extracts specific elements, and emits standard format. 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 a single, efficient paragraph: states purpose, process, output, and use cases. No superfluous sentences. Front-loaded with the action.

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 purpose, process, output, and use cases. No output schema, but the description explains the output is a text blob. It is sufficient for an agent to understand 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?

Input schema has 100% description coverage, so the schema already documents both parameters (url and max_links). The description mentions the parameters in passing but adds no new semantic information 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: generate an llms.txt file for a URL to aid AI crawlers. It explains the process (fetches page, extracts title/description/links) and output format. The tool is distinctive from its siblings, which are unrelated (e.g., search, AI visibility).

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not specify when not to use, but the context is clear enough for an agent to decide.

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, so the safety profile is clear. The description adds value by disclosing the data source ('Fraunhofer ISE energy-charts, keyless') and the return structure (MW and percentage shares, totals by category), which goes 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 front-loaded with the key purpose, includes example queries, and provides parameter details in a logical flow. It is slightly lengthy but every sentence adds value, making it efficient for its content.

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

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

Given 2 parameters with full schema coverage, no output schema, and the tool's complexity (moderate), the description is comprehensive. It explains the output (MW, percentage, category totals), input options, and data source, leaving no major gaps for typical use cases.

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

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

Schema coverage is 100%, describing both parameters. The description adds meaningful clarity: it notes that 'at' is optional and defaults to latest, and emphasizes that 'country' accepts names, 2-letter codes, and 'eu' for the aggregate. This enriches the schema definitions.

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

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

The description uses a specific verb ('shows') and clearly identifies the resource ('current electricity generation mix by fuel for a European country'), with concrete examples of queries. It distinguishes itself from siblings like 'electricity_price' or 'installed_power' by focusing on generation mix.

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

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

The description provides clear use cases ('answers "what is Germany's generation mix"') and specifies input formats (name or 2-letter code, including 'eu'). It does not explicitly state when not to use this tool or mention alternatives, but the context is sufficient.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by detailing the return object structure and that data arrays are aligned, providing useful behavioral context.

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

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

Two concise sentences: first states purpose, second specifies output format. No redundant words, and key information is front-loaded.

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

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

Given the simple parameters and lack of output schema, the description provides sufficient detail about the return format and units. The tool is straightforward and the description covers all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'annual or monthly series' which corresponds to time_step, but adds little beyond the schema's own 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 retrieves installed generation capacity by production type for a country, as time series. It specifies the return format and units, distinguishing it from related tools like total_power or generation_mix.

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

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

The description implies usage for installed capacity queries but does not explicitly state when to use this tool over siblings like total_power or public_power. No guidance on when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about return fields and the include_inactive parameter, but no extra behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with core purpose, no redundant information. Every word earns its place.

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

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

Given the simple tool with one optional parameter and no output schema, the description covers purpose, return fields, usage guidance, and parameter behavior completely.

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

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

Schema coverage is 100% for the single parameter, which already has a clear description in the schema. The tool description does not add additional parameter meaning, so baseline score of 3 applies.

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 return fields (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

Explicitly mentions when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternative actions.

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, so the description carries the full burden. It reveals rate-limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token flow (returned when filing without an account, pass it back later to read status). This exceeds what annotations provide.

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

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

Though long, every sentence earns its place: scope, use cases, exclusions, token mechanics, rate limits, and cost. The structure front-loads the purpose and then systematically covers usage, limitations, and follow-up, making it dense but efficient.

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

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

For a 4-parameter tool with no output schema, the description fully covers the lifecycle: when to use, when not to use, what to include, rate limits, and how to retrieve results via claim_token. It is complete for an agent to decide 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?

Schema covers 100% of parameters, so baseline is 3. The description adds value beyond schema by explaining the claim_token round-trip pattern and how to use it ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by advising users to describe issues in terms of Pipeworx tools rather than pasting prompts.

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 verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes the tool's scope with 'ONLY for tools served by this Pipeworx connection,' differentiating it from sibling research/data 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 explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use rule: if the tool came from a different MCP server, file it there instead. Also offers a practical heuristic for ambiguity ('Not sure? Pipeworx tool names are the ones this connection lists.').

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. Description adds value: data derived from CF analytics-engine, no PII, cached 5min-1h. 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?

Two sentences plus bullet list. Front-loads purpose, then use cases, then additional notes. Every sentence earns its place; no 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 single-param tool with no output schema, the description covers purpose, usage, and behavioral notes. Return structure (top tools, top packs, volume) is described. Completely adequate.

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

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

Schema coverage is 100% with enum description. Description adds context: shorter windows surface what's hot now, longer windows show steady-state demand. This adds meaning beyond the schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. It specifies the verb (returns) and resource (trending data), and distinguishes from siblings like discover_tools by focusing on aggregation of other agents' calls.

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?

Bullet list explicitly states three use cases: discovering hot data sources, confirming canonical tool, and checking alignment. While it doesn't explicitly say when not to use, the use cases are sufficiently clear for an AI agent to decide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: monotonicity checks, partition-sum calculation, similarity thresholds, placeholder filtering, and fill-check logic. It discloses that the tool analyzes rather than mutates, and explains edge cases like skipped_low_similarity and null signals. No contradictions with annotations.

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

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

The description is well-structured with clear sections but is somewhat verbose (multiple detailed explanations of modes, filters, fill check). It front-loads the main purpose and modes. While every sentence adds value, some redundancy exists (e.g., repeating partition_check explanation). Could be tightened slightly without loss of 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?

The description covers all major aspects: modes, input semantics, filtering, fill check, and response structure. However, the response structure is described only loosely (opportunities[] with fields), and there is no explicit list of every return field. Given the tool's complexity and lack of output schema, the description is mostly complete but leaves minor ambiguity about the exact output format.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains that 'event' expects a slug or full URL and is recommended for specific markets, while 'topic' is a seed question for cross-event scanning. It also clarifies that no args triggers a trending scan, which is not obvious from 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes multiple modes (no args, event, topic) and explicitly differentiates from sibling tools like polymarket_fill_risk. The verb 'Find' and specific resource 'arbitrage opportunities on Polymarket' make purpose unmistakable.

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

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

The description provides explicit guidance on when to use each invocation mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It also explains the semantic anchor and partition filter to avoid false positives, and points to polymarket_fill_risk for custom sizing. This gives 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 declare readOnlyHint=true and idempotentHint=true, which are consistent. The description goes far beyond annotations by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), how edge is calculated net of slippage, the output fields (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, and diagnostic structures (_diagnostics, filter_skips). This comprehensive disclosure fully informs the agent of behavioral traits.

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 purpose sentence and then structured into clear sections (model families, output fields, knobs, diagnostics). While comprehensive, it is somewhat verbose and could be tightened without losing meaning. However, given the tool's complexity, the length is justified.

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 fully describing the response structure: by_segment, fed_candidates, _diagnostics. It explains caching (KV-level, 1h, keyed on all knobs) and provides context for diagnosing empty segments (top-N stale, gate failures, knob drops). All aspects needed to use the tool correctly are covered.

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 input schema already describes all 9 parameters with detailed descriptions (e.g., min_kelly, slippage_pp). The description adds context about overall behavior and model families but does not significantly expand on individual parameter meanings beyond what the schema provides. The baseline of 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets to find edge opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes itself from siblings by focusing on 'what should I bet on today' and detailing three model families, making it specific and differentiated.

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

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

The description provides clear usage context: agents discover opportunities without paging hundreds of markets. It explains tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and notes that Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, and the description does not contradict these. It adds rich behavioral context: reads snapshots, returns time-series, computes trends and decay, includes expired opportunities, and documents limits (60-day TTL, daily closes, not intraday).

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

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

The description is dense and front-loaded with the core purpose. It uses bold for key terms and a list-like structure for response fields, making it scannable. While slightly long, every sentence provides useful information.

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

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

Given 2 parameters, no output schema, and no enums, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and limitations. It is complete enough for an agent to select and invoke the tool without confusion.

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 repeats defaults but adds minimal new meaning beyond the schema. Baseline 3 is appropriate as the schema already provides sufficient 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?

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about how long an edge has existed and whether it's shrinking, distinguishing it from sibling tools like polymarket_edges (current edges) and 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?

The description explains the value of using this tool (e.g., a 3-week-old wide edge is different from a fresh one) and implies when to choose it over alternatives. While it doesn't explicitly state when not to use it, the context is clear enough for an AI agent to infer appropriate usage.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true, indicating a safe, read-only analysis tool. The description adds behavioral details like walking the ladder, returning fill details, and warning about forced_directional_risk, which aligns with and enriches 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 well-structured with clear sections for single-market and basket modes, but it is somewhat verbose, repeating details that could be consolidated. For example, the parameter descriptions in the schema already cover defaults, so some redundancy exists. However, it is 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?

Given the lack of an output schema, the description thoroughly explains return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs). It also covers risks like partial fills and forced_directional_risk, making the tool's behavior fully understandable without needing to invoke 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% with all parameters described. The description adds value by explaining single-market vs basket mode, default values, and the interpretation of size_usd for baskets. It also mentions clamping range (10–1,000,000), 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 checks 'realizable-vs-theoretical edge' against live order book depth. It distinguishes between single-market and basket modes, listing specific outputs like top_of_book, vwap_fill_price, and verdict. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It further explains why: theoretical overround is not capturable on thin books and partial fills create directional risk. This is comprehensive guidance.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate a safe, read-only operation. The description adds behavioral context: it explains the two cases for compatibility_warning, the temporal_alignment field, and the meaning of skipped_cross_type/subtype counters. It also outlines the response structure (leg-by-leg prices and matched spreads). 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 structured with clear sections (modes, response, safety fields, temporal alignment), but it is relatively long. However, every sentence provides useful information given the tool's complexity. A minor reduction in verbosity could improve conciseness without losing value.

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

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

The description is comprehensive: it explains the output structure (leg-by-leg prices, top_spreads_pp, safety fields), the meaning of compatibility_warning and temporal_alignment, and the implications of skipped comparisons. With no output schema, the description fully covers return values and prerequisites. Sibling tools are well-distinguished.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning beyond the schema: it explains the two operational modes, the explicit parameter override logic, and lists the pre-mapped topic values. The schema's examples (e.g., 'topic': 'fed') are also reused, enhancing understanding.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies that it computes price spreads between two prediction markets and distinguishes between two modes (topic and explicit). This differentiates it from siblings like polymarket_arbitrage (within Polymarket) or other analysis tools.

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

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

The description provides explicit guidance on when to use each mode: topic for 10 pre-mapped shortcuts, explicit for custom pairings. It warns about compatibility_warning scenarios and temporal_alignment meaning, and states that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This helps the agent decide when the tool's output is reliable.

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

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

Annotations declare readOnlyHint and idempotentHint, indicating safety. Description adds details on return structure (unix_seconds, production_types), timestamp alignment, and units (MW), going beyond annotations. No contradiction.

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

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

Two sentences plus return format note. Purpose is front-loaded, details are concise, and every sentence adds value.

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

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

Given annotations and no output schema, the description covers input, output structure, and units. Missing error handling or data availability details, but sufficient for a read-only query tool.

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

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

Schema covers all parameters with descriptions; description adds examples and context (e.g., country codes). However, the description does not significantly enhance understanding beyond what the schema provides.

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

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

Description clearly states it returns electricity generation by production type for a country over a date range. It specifies the return format and units, distinguishing it from siblings like total_power, electricity_price, etc.

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?

Describes the tool's functionality and parameters but does not explicitly guide when to use it over siblings (e.g., total_power, generation_mix). The context is implied but not explicit.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (identifier-based) and behavior when key is omitted (list all keys).

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 unnecessary words. Front-loaded with core action and key use case. Efficient and clear.

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

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

For a tool with one optional parameter and no output schema, the description covers core functionality, scope, and sibling relationships. Return format is not described but is minor given simplicity.

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

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

Schema coverage is 100%, baseline 3. Description adds that omitting key lists all keys and provides examples. Adds value beyond schema by explaining the optional behavior.

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 verb ('Retrieve' or 'list') and resource ('saved values/keys'). Distinguishes from siblings by mentioning 'remember' and 'forget' explicitly.

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 case: look up stored context to avoid re-derivation. Mentions pairing with remember/forget, but doesn't specify when not to use or provide alternative tools beyond siblings.

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

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

Annotations declare readOnly and idempotent. Description adds that mark_read:true flags events so next call shows newer ones, explaining the side-effect beyond a simple read. 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?

Four concise sentences with no redundancy. Primary purpose stated first, then details, then polling guidance. Every sentence adds value.

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

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

For a filtered list tool with comprehensive annotations and schema, the description covers return fields, filter options, side effects of mark_read, and alternative access. No output schema needed since return is clearly 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 coverage is 100%, but description adds practical examples: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and explains mark_read's effect. This supplements the schema descriptions well.

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 'Pull fired events from your subscription feed', clearly stating the action and resource. It specifies the return includes 'source, citation_uri, and raw event payload', distinguishing this tool from siblings like subscribe/unsubscribe and other data retrieval 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 usage context with 'Polls work fine' and mentions an alternative endpoint for scripts/dashboards. While it doesn't explicitly state when not to use, the alternative guidance is helpful for deciding between tool and direct HTTP access.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds valuable behavioral details: fans out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail pending API sunset, and output structure. Could mention rate limits but not necessary given readOnly.

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 efficiently packs user intent, data sources, input format, output structure, and sibling differentiation without wasted words. Front-loaded with relatable examples.

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 sufficiently explains return format (grouped changes, total count, citation URIs). Covers input format, data sources, fallback behavior, and directs to entity_profile for static needs. Complete for moderate 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%, and description adds contextual examples for each parameter (since formats, value as ticker or CIK, type limited to company). Exceeds baseline expectation.

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 begins with user query examples, then clearly states the tool's purpose as a change feed for a company in a time window, listing specific sources (SEC, GDELT/GNews, USPTO) and distinguishing from sibling 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?

Explicitly says when to use this tool ("what's new" queries) and when to use entity_profile (static profile regardless of window). Also provides guidance on the since parameter format and recommendation.

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

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

Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already convey mutation and idempotence. Description adds scope-by-identifier and retention details, but doesn't mention explicit overwrite behavior (implied by idempotency). No contradictions.

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

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

Three sentences: first clearly states purpose and scope, second gives when-to-use and examples, third adds technical details (scoping, retention) and sibling pairing. 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?

Covers purpose, usage, scope, retention, and siblings. For a write-only tool with no output schema, this is complete and self-contained.

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

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

Schema covers 100% of parameters with descriptions. The description reinforces naming conventions (e.g., 'subject_property', 'target_ticker') and notes value can be any text, adding slight extra 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 states a specific verb ('Save') and resource ('data ... across conversations/sessions'), clearly distinguishing it from siblings 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides examples (resolved ticker, target address, user preference, research subject). Also mentions pairing with recall and forget, and contextualizes retention (persistent vs 24h).

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

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

Annotations already indicate readOnly, openWorld, idempotent hints. The description adds behavioral details: returns a list of series with percent data, timestamp-ordered, most recent last, and default to 7 days. It also mentions keyless access, providing 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 moderately long but well-structured: purpose, key features, return format, data details, and optional dates. It is front-loaded with the core purpose. Each sentence adds value, though slight redundancy in explaining defaults.

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 explains the return format and how to use it. It covers the tool's purpose, parameters, and data interpretation. It does not compare to siblings but is self-contained for the task.

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 parameter descriptions. The description adds value by explaining the data interpretation (percent of load, series structure) and that the last value is the current share. It reinforces defaults and provides examples, aiding understanding of parameter usage.

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 the renewable share of a country's electricity load, provides an example question, and mentions keyless access. It specifies the data structure and ordering, distinguishing it from sibling tools like generation_mix or total_power by focusing on share of load.

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

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

The description explains when to use the tool (e.g., 'Answers what share of Germany's electricity load is renewable right now') and notes the default date range. It implies usage for current or historical renewable share, but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=true, and non-destructive. The description adds substantial context: source-labelled identifiers, explicit 'unresolved' field, graceful degradation of LEI/FIGI enrichment, and multi-endpoint cascading. These enrich the agent's understanding 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 long but dense; every sentence adds value, including user-query examples, usage guidance, supported types, and fallback behavior. It is structured with 'SUPPORTED TYPES' and logical flow. It could be slightly more concise, but the complexity justifies the length.

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

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

With no output schema, the description thoroughly explains return values for both entity types (company: CIK, ticker, LEI, FIGI, source labels, unresolved; drug: RxCUI, ingredient, brand, citation). It also covers graceful degradation and the cascading internal lookups, making it 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%, with both parameters fully described and examples. The description repeats the accepted input formats (ticker/CIK/name, brand/generic) and adds output context, but does not provide new parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers with a specific verb-resource pair ('resolve name to ID'). It includes example queries and distinguishes itself from siblings by positioning as the first step when an ID is needed, and lists the specific identifiers it resolves.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it probes each entity with 'ai_visibility_check', ranks by score, and returns 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?

Two sentences: first states core action, second provides use case and return structure. No extraneous words, front-loaded with key purpose.

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

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

Given no output schema, the description fully explains the return format (ranked list with score, confidence, signal density per entity). It explains the subject/competitor distinction and optional parameters. Covers all necessary behavioral details.

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

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

Schema description coverage is 100%, so each parameter is described in the schema. The description adds minimal extra meaning beyond restating that entities are compared and that the first is treated as subject.

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 specifies a concrete action ('Compare AI visibility across multiple entities side-by-side') and resource ('competitor AI presence'). It explicitly distinguishes from sibling tool 'ai_visibility_check' by noting it probes multiple entities and ranks them.

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

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

The description states the tool is 'useful for competitive AI-marketing audits' with an example question. It implicitly contrasts with single-entity check (ai_visibility_check) but does not explicitly list alternatives or when not to use.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds: fans out across multiple services, graceful degradation with sources_failed list, and bundlephobia first-measurement delay of 5-30s. No contradictions with annotations; all are consistent and complementary.

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

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

The description is well-structured with a clear opening, usage guidance, return details, and caveats. While slightly lengthy, each sentence adds valuable information without redundancy. Minor opportunity to tighten phrasing, but overall 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?

Despite lacking an explicit output schema, the description details the return structure (summary block fields, per-advisory detail, links, alternative versions) and explains partial failures. Given the tool's complexity (multiple APIs), this level of detail is sufficient for agent understanding.

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

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

Schema coverage is 100%, but description adds value by explaining that scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. This clarifies common usage scenarios 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 a composite check for evaluating npm packages, covering license, advisories, bundle size, and more. The verb 'scan' and resource 'dependency' are specific, and it distinguishes from siblings by focusing on npm ecosystem and aggregation of multiple data sources.

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

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

Explicitly says to use when an agent asks about safety, popularity, or size of an npm package. Also specifies ecosystem scope (NPM only in v1) and directs other ecosystems to an alternative tool (deps.dev:version). Provides guidance on partial failures and expected timing for bundlephobia.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details embedding model (BGE-base-en), chunking (500-char overlapping windows), input cap (200K chars with truncation flag), and output structure (passages with offsets and similarity scores). This is comprehensive.

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, front-loaded with key information, and every sentence adds value. No wasted words, approximately 100 words covering purpose, usage, behavior, and limitations.

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 (semantic search, chunking, embeddings) and absence of an output schema, the description fully explains what is returned (passages with offsets and scores), truncation behavior, and pairing recommendations. It leaves no obvious gaps for an AI agent.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds context: text should be 'already pulled', query is 'natural-language', and limit default is 5. This adds meaningful guidance beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with examples like SEC 10-K and articles. It mentions pairing with ask_pipeworx_grounded but does not explicitly differentiate from other sibling search tools, leaving some ambiguity.

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

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

Explicitly says to use when the record is too large for the prompt and saves context. It suggests pairing with ask_pipeworx_grounded, but lacks exclusion criteria or a broader set of 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: SMS has a 10/day cap, webhook auto-disables after 10 consecutive failures, and phone numbers must be verified. These are important for an agent to understand side effects and limits.

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

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

The description is somewhat long, but front-loaded with the core purpose. It uses clear sections (supported types, delivery channels) and lists limitations. Some redundancy could be trimmed (e.g., repeated mention of phone verification), but it remains structured and readable.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers purpose, return value (subscription id), required auth, type-specific params, delivery options, and limitations (SMS cap, webhook auto-disable). It also mentions the alternate feed pull method. All key aspects are addressed for a subscription creation 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%, but the description provides detailed examples for each type's params (e.g., sec_8k items, polymarket_edge topics) and explains delivery channel requirements (phone verification, email validation, webhook signing). This adds significant meaning beyond the schema's 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 clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It specifies verb (create), resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe. The text also enumerates supported types and delivery channels, leaving no ambiguity.

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 requires a Pipeworx OAuth account and excludes anonymous/BYO users. It provides context on when to use the feed channel (always on, pull via recent_alerts) and mentions alternatives implicitly. While it does not compare directly to siblings, it gives enough context to decide when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about returning category-bucketed example questions drawn from a live catalog, which is valuable 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?

Description is long but well-structured with a clear opening, enumeration of categories, and usage guidance. It could be slightly more concise but remains informative and front-loaded.

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

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

No output schema exists, but the description thoroughly explains what the tool returns. Given the simple interface (one optional param) and the detailed description of output categories, the description 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 has 100% coverage with description for topic parameter. The tool description adds meaning by listing example values and explaining that omitting it 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 explicitly states it is the onboarding entry point and returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like ask_pipeworx by being the first thing to use when the agent does not know what Pipeworx can do.

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?

Clearly states '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 when to pass optional topic argument vs calling with no arguments.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds output structure details (timestamp alignment, MW units) and clarifies the return format, which provides useful behavioral context beyond annotations.

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

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

Two sentences cover purpose, scope, output structure, and units with zero waste. All information is front-loaded and essential.

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 3-parameter tool with no output schema, the description covers the key aspects: what it returns, units, and the 'all' country option. It lacks error conditions or limits, but given the simplicity, it is fairly complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add new parameter details (e.g., date format, defaults) beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('returns') and resource ('total electricity generation/load for a country') and clearly distinguishes from siblings like 'generation_mix' or 'electricity_price' by specifying aggregate power data.

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

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

The description implies usage for aggregate power queries but does not explicitly state when to use this tool over alternatives (e.g., 'generation_mix' for breakdown). No when-not-to-use guidance is provided.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), it discloses that the row is deactivated not deleted and that historical events remain accessible. No contradictions.

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

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

Two sentences, front-loaded with action and resource, no redundant words.

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

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

For a simple mutation with no output schema, the description explains the effect (deactivation, not deletion, historical data preserved) and ownership rule, making it fully 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?

The description adds meaning by specifying the 'id' comes from 'subscribe', and schema already covers the parameter with 100% description 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 uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing a key usage condition. It also links to 'recent_alerts' for historical data, aiding tool selection.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses crucial behavior: what could_not_verify means (the check did not happen, carries verification_error{stage,detail}, and must not be shown as evidence), what unsupported means (no source coverage), and the return structure (verdict, evidence with citation, reasoning). This is precisely the kind of context that helps agents interpret results correctly.

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

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

The description is dense but every sentence earns its place: trigger phrases, usage guidance, pipeline distinction, return values, error semantics, and efficiency note. It is front-loaded with how to recognize calls and structured logically. No wasted words, despite the length.

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

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

No output schema means the description must explain return values, and it does: verdict enums, actual value with citation, and reasoning. It also covers error conditions, the two routing paths, and performance benefits. For a tool of this complexity, the description is fully complete and leaves no critical gaps for an agent.

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

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

Schema coverage is 100%, but the description adds significant value by explaining tolerance_pct semantics: it overrides the implied tolerance, defaults to wording-capped-at-5, and suggests 1–2 for hallucination detection. It also provides concrete claim examples for the claim parameter, going beyond the schema's basic description.

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

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

The description states exactly what the tool does: 'natural-language claim verification against authoritative sources.' It includes trigger phrases like 'fact check' and 'verify the claim that...' and details two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for others), which clearly 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 says to use it 'whenever the agent needs to check whether something a user said is factually correct' and even notes it 'replaces 4–6 sequential calls,' implying it is a consolidated alternative. However, it does not explicitly name alternative sibling tools or state when not to use it (e.g., for open-ended research), so it falls short of a 5.

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