Elexon

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: default free model, the need for an API key for Anthropic, and the response structure per-model. This enhances transparency 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 three sentences, each serving a purpose: what the tool does, default and paid model details, and use cases. No unnecessary words, well-structured, and front-loaded with the core 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?

Despite lacking an output schema, the description details the return structure (per-model score, confidence, signals, raw_response + combined view). It covers required and optional parameters and their implications. For a tool with 4 parameters and no output schema, this is complete.

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

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

All parameters are described in the schema (100% coverage). The description adds meaning by explaining the default model, the purpose of _apiKey (passed through to Anthropic), and how the 'context' parameter helps disambiguate. This adds value beyond the schema.

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

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

The description clearly states the tool's verb (probe, score), resource (LLMs, visibility of a brand/product/topic), and scope. It distinguishes itself from siblings by focusing on AI visibility scoring, which no other tool does.

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

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

The description explicitly states when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. paid models. It does not provide explicit alternatives or when-not-to-use guidance, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it routes to thousands of tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a fast single call. No contradictions with annotations.

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

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

The description is long but densely informative and well structured: preference rule first, then behavior, trigger patterns, examples, routing guidance, and escalation paths. Every section earns its place, and the most important decision guidance 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?

For a broad query-router tool with a rich annotation set and a simple one-required-parameter schema, the description covers the key facts an agent needs: scope, supported domains, behavior, output style with citations, and when to escalate to siblings. No critical gap is left for an agent to infer.

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% and all six parameters are documented as aliases for the same natural-language question. The description reinforces that the input is a question but does not need to add per-parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific resource and behavior: asking a natural-language question that is routed to one of 5,706 tools across verified sources, returning a structured answer with citation URIs. It distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell it apart 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?

The description explicitly says to prefer this over web search, declares it the default entry point for most questions, and gives concrete step-up conditions to ask_pipeworx_grounded and deep_research. It also provides trigger phrases and examples, making when-to-use unambiguous.

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

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

Annotations already provide readOnly/openWorld/idempotent hints, and the description adds critical live behavior: candidate improvements toggle on during tests, none is active as of 2026-07-26, and it currently behaves identically to ask_pipeworx. It also preempts a misconception by stating it 'falls back to nothing' and is a full working router.

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 dense sentences, each carrying distinct information: beta status, current active-candidate state, usage instruction, and no-fallback clarification. The key routing state 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?

For a universal router with a single required parameter and no output schema, the description covers current runtime behavior, relationship to the sibling, and safety. Nothing an agent needs to decide between this and ask_pipeworx is missing.

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

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

Schema description coverage is 100% with question and its aliases fully documented, so the baseline applies. The description only says the arguments are the same as ask_pipeworx, which adds no semantic value beyond the schema.

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

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

The description states exactly what the tool is: a beta, identical-routing version of ask_pipeworx with the same 5,706 tools and response shape. It explicitly names the sibling ask_pipeworx, distinguishing this as the experimental edge while clarifying it is still a full working router.

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 an explicit when: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also references the stable router as the comparison alternative and explains that its results are evaluated for merging, making the intended use clear.

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

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

Annotations already mark it read-only, open-world, and idempotent, and the description adds valuable behavioral context beyond those: exact return shape, explicit refusal reasons, the constraint that evidence must be a verbatim quote, and the extra LLM call cost. This is strong transparency for an agent.

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 contributes: purpose, internal behavior, return/refusal contract, usage guidance, and cost trade-off. It is front-loaded with the defining trait and never wastes words on restating the name or annotations.

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 and what refusal reasons look like. Combined with the provided annotations, an agent has enough context to decide when to call it, what to expect, and how to interpret the result — nothing essential is missing.

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

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

All six parameters are aliases for the same natural-language question, and the schema already documents them at 100% coverage. The description doesn't add parameter-level detail beyond describing the internal routing, which is appropriate but not extra semantic value. Baseline 3 is warranted.

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 tool-selection process as ask_pipeworx and extracts answers strictly from tool results. It also distinguishes itself from sibling ask_pipeworx by stressing groundedness and refusal behavior when data doesn't directly answer.

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

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

Explicitly states when to use the tool — when an answer will be quoted, cited, or acted on and the agent must not invent facts — and when to avoid it, saying to prefer ask_pipeworx for casual lookups. It also names the sibling alternative and the trade-off, making selection unambiguous.

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

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

The annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds extensive behavioral context: fan-out parallelism, response shapes (market, analysis, evidence), resolver contract with match confidence and alternatives, parent event extractor, news fallback mechanisms, safety short-circuits for low-confidence or closed markets, illiquid wide-spread handling, and cancellation rule parsing. This far exceeds 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 thorough but somewhat long. It is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.), front-loading the core purpose. While every sentence adds value, the length could be trimmed without losing clarity, given the complexity.

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

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

Given the tool's complexity (3 params, no output schema, many response fields), the description covers all aspects: market resolution, classification, fan-out, evidence packet details, match confidence, parent event extraction, news fallback, safety behaviors, and cancellation rules. It explains response shapes and edge cases comprehensively.

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

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

The input schema has 100% coverage, but the description adds significant meaning: it explains the market parameter can be slug, URL, or question text; depth enum with defaults; include_raw boolean with guidance on when to use true/false. It provides examples and clarifies behavior, making the parameters far more understandable.

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 input formats (slug, URL, question text), the process (resolve, classify, fan-out), and output (evidence packet plus comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It includes classifiers and fan-out examples that help the agent decide when to use this tool. However, it does not explicitly mention when to avoid it or compare with alternatives like polymarket_edges, though the context is strong.

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

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

The description fully discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of fiscal years, sorting by primary metric, and output format with citation URIs. This goes well beyond the annotations, which already mark it as read-only and idempotent.

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 slightly verbose with multiple examples but remains efficient for the complexity. All sentences are informative, no fluff.

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

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

Given no output schema, the description adequately covers return format (paired data, citation URIs, sorted by metric). Data sources, entity types, and constraints are fully explained.

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

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

With 100% schema coverage, the description still adds significant value: it explains what each 'type' enum pulls (company: financials; drug: adverse events) and gives concrete examples for 'values' (tickers vs drug names, count constraints). No parameter is left unexplained.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one call, with specific verb 'compare' and resource 'entities'. It distinguishes itself from sequential single-pack lookups, which is a key differentiator among siblings.

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

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

The description explicitly prefers this tool over sequential lookups and provides natural language triggers. It lacks explicit when-not-to-use scenarios, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: account/payment requirements, parallel tool routing, a findings packet structure with gaps[] and contradictions[], timing expectations of 15-90s, and guarantees that citations are only included when actually fetchable. It also clearly states that the tool never invents answers and semantically excerpts large records. This goes well beyond the annotations and is consistent with 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 long but each section earns its place: account requirement, core mechanism, use-case guidance, depth behavior, citation semantics, and latency. It is front-loaded with the most actionable constraint (account/sign-in) and uses clear contrasts. Minor redundancy exists because depth behavior is also fully described in the schema, but the density is justified for a high-complexity research 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?

Despite having no output schema, the description enumerates the findings packet fields (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), so the agent knows what to expect. It covers prerequisites, exclusions, timing, and failure behavior for unsupported topics. For a tool of this complexity, no critical operational detail appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already fully explains depth's facet counts, gap-recovery hops, and contradictions[] scan. The description adds genuinely useful extra semantics by noting that 'thorough' needs a paid plan, clarifying the expected latency per depth level, and emphasizing that 'question' can be broad and multi-part. This adds meaning beyond the schema, though not by a large margin.

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 and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' that 'Decomposes your question into focused facets' and returns a findings packet. It explicitly distinguishes itself from open-web search and from ask_pipeworx, making the tool's role unambiguous. The comparison to sibling tools further sharpens what this tool uniquely does.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' contrasted with 'For a single lookup use ask_pipeworx' and for 'BREAKING or colloquial CURRENT-NEWS' topics. It even names the fallback when the user is not signed in, saying 'use ask_pipeworx instead.' This fully routes the agent to the correct alternative.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: results are 'top-N most relevant' and 'each result is ready to call directly, no second schema lookup needed.' 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 succinct, with only a few sentences. It front-loads the core purpose ('Find tools by describing the data or task') and efficiently packs domain examples, return structure, and usage guidance without unnecessary verbiage.

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 discovery role, the description covers all necessary context: what it does, when to use it, what it returns (names, descriptions, full input schemas with curated examples), and that results are ready to call. No output schema is provided, but the description adequately describes the return 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 description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that 'query' accepts aliases (task, q, description, search) and provides concrete examples ('look up FDA drug approvals', 'analyze housing market trends'). This goes beyond the schema's minimal descriptions.

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

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

The description clearly states 'Find tools by describing the data or task,' with a specific verb ('Find') and resource ('tools'). It lists numerous example domains, making the purpose unambiguous. This tool is distinct from its siblings, which are specialized tools, as it serves as a discovery gateway.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. It does not explicitly state when not to use or list alternatives, but the context of sibling tools makes the role clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond that: 'Keyless' (no authentication), the finite scope 'all 84', and what each entry contains (code, holdings, window parameters). No contradiction with annotations.

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

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

Three sentences, each contributing distinct information: scope, content coverage, and usage instruction. It is front-loaded with the purpose and avoids filler, though the middle sentence is dense with category lists that could be lightly restructured for scannability 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?

For a tool with one optional parameter and no output schema, the description covers the main needs: what the tool returns (dataset code, contents, window parameters), how to filter (search keyword), and when to use it (before query_dataset). It does not detail the exact output format, but that is not essential for this simple listing 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 schema description covers 100% of the single parameter, already explaining the case-insensitive keyword matching against code and title with examples. The description's phrase 'Search by keyword' adds no new semantic meaning 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 directory ('Directory of all 84 Elexon BMRS Insights datasets'), specifies the resource (datasets) and its exact relationship to query_dataset, making it immediately distinct from sibling tools like query_dataset, elexon_system_prices, or generation_by_fuel. The verb and scope are specific and unambiguous.

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

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

It explicitly states when to use the tool: 'Search by keyword to find the code for a subject before calling query_dataset.' This gives the agent a clear, actionable condition and links to the primary sibling, while also implying a discovery role. No other alternatives are mentioned, but the guidance is concrete and sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond that: the endpoint is keyless and is not reachable via query_dataset. It does not describe error behavior or response shape, but the annotation coverage lowers the burden and the added access constraints are valuable.

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 with no wasted words. The key facts are front-loaded: what the tool returns, the units, the source identifier, the cash-out context, and the access constraint that differentiates it from query_dataset.

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 two-parameter read-only tool with no output schema, the description is complete: it enumerates the returned fields, units, settlement-period granularity, source, and access model. The 48-row default behavior is covered in the input schema. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents settlement_date and settlement_period with examples and the 1-48 range. The description adds output context (GBP/MWh, field names) but does not materially expand parameter semantics beyond what the schema provides. 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 resource: Great Britain electricity imbalance prices for a settlement day, with specific fields (system buy/sell price, derivation code, reserve scarcity price, net imbalance volume) and units. It also distinguishes itself from query_dataset by naming the route constraint, so an agent can tell exactly what this tool offers.

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

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

The description explicitly explains when to use this tool: for Elexon system prices/cash-out prices. It also tells the agent why query_dataset cannot be used instead ('Elexon serves it outside the /datasets routes'), giving clear routing guidance among sibling tools.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds context about parallel fan-out, soft-fail for patents, and specific returned fields. 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 relatively long but well-structured with example queries first, then details. Every sentence adds value; minor conciseness improvement possible.

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 and lack of output schema, the description thoroughly covers data sources, return fields, parallel execution, and limitations. Complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with both parameters described. Description adds value by clarifying that value can be ticker or CIK, and explicitly states names are not supported, going beyond schema.

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

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

The description clearly states that the tool provides a full cross-source profile of a US public company in one call, listing specific sources and returned fields. It distinguishes itself from siblings like resolve_entity.

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 advises to prefer this tool over chaining single-pack lookups for holistic views, and excludes names with a directive to use resolve_entity first. Provides example queries.

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

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

Annotations already provide destructiveHint=true. Description adds context about clearing sensitive data, but no contradiction. Adds value 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, concise, front-loaded with purpose. No unnecessary words.

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

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

Simple tool with one param and clear annotations; description is fully adequate for agent to invoke correctly.

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

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

Schema covers 100% of parameters with description for 'key'. Description does not add further meaning beyond the schema; baseline 3.

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

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

Clearly states the action (delete) and resource (stored memory by key). Differentiates from siblings by mentioning 'pair with 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?

Explicitly states when to use: context stale, task done, or clear sensitive data. Also suggests pairing with 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?

Description details the process: fetching the page, extracting title/description/key links, and emitting standard llms.txt format. This adds value beyond annotations, which already indicate read-only and idempotent behavior, by explaining the internal steps and output nature.

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

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

Three sentences, front-loaded with the main action. No redundant words. Efficiently conveys purpose, process, and use cases.

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 sufficiently describes the output as a single text blob. Parameters are fully covered. Minor gap: no mention of error handling or network failure, but acceptable for this 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 covers 100% of parameters (url and max_links) with adequate descriptions. The description does not add extra parameter-level details, so baseline 3 is appropriate.

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

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

Description clearly states the tool generates an llms.txt file for a URL, with a specific verb and resource. It distinguishes itself from sibling tools as a unique generation utility for AI crawler indexing.

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

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

Description enumerates three explicit use cases (client indexing, personal projects, competitor auditing). While it lacks an explicit 'when not to use' or alternative suggestions, the use cases are sufficiently clear 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 convey readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the data is keyless and covers 48 periods per day, which is useful but not substantial 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 a single concise paragraph that front-loads the core purpose, listing details efficiently without extraneous words. Every sentence adds value.

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

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

Despite no output schema, the description indicates the return format (MW per fuel type) and lists fuels, which is sufficient for a simple read-only data retrieval tool. Input schema fully covers parameters. Annotations handle behavioral 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 description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly specifies the tool returns 'Great Britain half-hourly electricity generation by fuel type', names the dataset (Elexon BMRS FUELHH), lists fuel categories, and clarifies keyless structure with 48 settlement periods per day, distinguishing it from siblings like 'system_demand'.

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 what the tool does but provides no explicit guidance on when to use it versus alternatives such as 'system_demand' or 'query_dataset'. Usage context is implied but not directly 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count), enhancing transparency. 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 concise sentences: first states purpose and output, second gives usage guidance. No unnecessary words, front-loaded.

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

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

The tool is simple with one optional parameter and no output schema. The description sufficiently covers what it does, what it returns, and when to use it. 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%. The description does not add meaning beyond the schema's description of 'include_inactive' parameter; 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 verb 'List' and the resource 'subscriptions', with scope 'caller's active'. This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly tells when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it does not mention 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?

Beyond the neutral annotations, the description discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later'), and the team's read cadence and roadmap influence. It also warns against pasting end-user prompts, adding behavioral nuance not inferable from 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 the description is longer than average, every sentence earns its place. It is front-loaded with the core purpose, then covers usage conditions, scope exclusions, content rules, the claim_token mechanism, and operational details. There is no fluff or redundancy — the length is justified by the tool's multiple subtle behaviors.

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—no output schema, all-neutral annotations, and nuanced workflow—the description covers all necessary context: when to use, when not to use, what to include, how the claim_token follow-up works, rate limits, quota, and impact. An agent can correctly select and invoke this tool without needing additional documentation.

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 describes all parameters with 100% coverage, so a baseline of 3 applies. The description adds valuable cross-parameter guidance: it explains how claim_token should be used alone ('with no other arguments') and instructs message formatting ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), enriching the schema's basic 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 opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately enumerates the categories (bug, feature/data_gap, praise). It clearly distinguishes this tool from sibling research and data tools by focusing on feedback about the Pipeworx connection itself, not on any data operation.

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

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

The description gives explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion criterion: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for other MCP servers. This is exemplary alternative-scoping 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?

Description adds value beyond annotations by stating it is self-aggregating from CF analytics, no PII, and cached 5min-1h. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false.

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

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

Description is concise, front-loaded with main purpose, followed by use cases and technical details. Every sentence adds value without redundancy.

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

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

Given simple schema, full annotations, and single parameter, the description completely covers purpose, usage, and behavioral aspects. No output schema 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?

Single parameter with 100% schema coverage. Description adds meaning by explaining that shorter windows surface 'hot right now' and longer windows show 'steady-state demand', beyond the enum values.

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume over a recent window', specifying verb and resource. It distinguishes from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on trending 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 provides three explicit use cases (discovering hot data, confirming canonical choice, aligning use case) but does not mention when not to use the tool 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 indicate readOnly, idempotent, non-destructive behavior. The description adds extensive behavioral detail: scanning scope, partition checks, Jaccard similarity anchor, placeholder filtering, fill check logic, and trade 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, front-loading the purpose and usage modes, then detailing constraints and outputs. It is somewhat lengthy but every sentence adds value, making it efficient for an AI agent to parse.

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

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

Despite lacking an output schema, the description thoroughly explains the return structure (opportunities array with fields, partition check details, fill check results). It covers all input options, filters, and edge cases, making the tool fully understandable.

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

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

Schema covers both parameters with descriptions, but the description adds crucial context: event accepts slugs and full URLs, topic is a seed question for cross-event scanning. It explains behavioral differences between modes far beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies both the action (find) and the domain (Polymarket arbitrage opportunities), distinguishing it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly explains when to use each mode: no args for a trending scan, 'event' for specific market partition checks, and 'topic' for cross-event scanning. It also provides guidance on when not to trade (realizable_edge_pp ≤ 0) and directs custom sizing to polymarket_fill_risk.

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 destructiveHint=false. The description adds extensive behavioral context: model details, edge calculation, slippage, caching at KV level for 1h, and Fed candidate limitations. 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?

The description is information-dense and well-structured, front-loaded with purpose. While somewhat lengthy due to complexity, every sentence adds value. Could benefit from formatting like bullet points.

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

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

Given no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and all relevant fields. It covers caching, edge knobs, and filter logic, making it complete 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%. The description goes far beyond, explaining defaults, usage, and rationale for each parameter (e.g., slippage_pp explains Polymarket fees, min_liquidity provides a concrete example). This adds significant value.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes three model families, differentiating it from sibling tools like 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 explicitly says it is built for discovering opportunities, implying usage for betting decisions. However, it does not directly compare with alternatives or state when not to use, leaving some inference to the agent.

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

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

The description discloses important behavioral details beyond the annotations: limits (60-day TTL, decay from daily closes, not intraday), snapshot gaps, and that decay numbers come from daily closes. This adds value without contradicting 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: purpose, args, response breakdown, limitations. It is dense but every sentence adds value. Slightly long but appropriate for the complexity; front-loads the core idea.

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

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

Despite no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their meaning, along with constraints (TTL, decay computation). It is comprehensive for a read-only telemetry 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 already provides descriptions for both parameters (days, window) with defaults and clamping/options. The description adds context on how they affect the output but does not provide significant new details 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 tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It uses specific verbs and resources, and the example of a fresh vs. old wide edge illustrates the need. This distinguishes it from siblings like polymarket_edges (raw 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 implies when to use this tool (for historical persistence analysis) via the example, but does not explicitly compare to alternatives or state when not to use it. It lacks direct 'use this for X, use that for Y' 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?

Description details behavior: walks ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, verdict. Warns about partial basket fills leading to unhedged positions. This is consistent with annotations (readOnlyHint, idempotentHint, openWorldHint) and adds significant behavioral context beyond annotations.

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

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

Description is relatively long but well-structured with clear sections (SINGLE-MARKET vs BASKET) and bold for emphasis. Every sentence adds value. Slightly wordy but not excessive.

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

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

No output schema exists, so description bears full burden. It comprehensively lists return fields for both modes (e.g., top_of_book, vwap_fill_price, profit_usd, thin_legs, forced_directional_risk) and explains the verdict system. Also addresses edge cases like partial fills and unhedged positions.

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 extra meaning: explains default size_usd interpretation (max spend vs target proceeds), side defaults for basket (auto based on partition sum), and value clamp (10–1,000,000). This goes beyond schema descriptions, e.g., clarifying that size_usd in basket mode is 'settlement notional — shares per leg'.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools 'polymarket_arbitrage' and 'polymarket_edges' by positioning itself as a pre-execution check. Verb 'check' and resource 'fill risk' are specific and well-defined.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'. Also specifies requirement of one of 'market' or 'event'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, and the description does not contradict them. It adds substantial behavioral detail beyond the annotations: compatibility fields can be non-empty even when matches exist, unclassified legs are never paired, `premapped_pairing_unverified` is always set in topic mode, and most pre-mapped topics currently return warnings. This is exceptionally transparent about the tool's limitations and edge cases.

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 and dense, but it earns most of its length by covering modes, response shape, safety fields, compatibility codes, and pairing caveats — useful for a tool with no output schema. It is structured with labels like `TWO MODES`, `RESPONSE`, and `SAFETY FIELDS`, which aids navigation. Some repetition of the 'pre-mapped ≠ tradeable' warning could be trimmed, so it is not a 5.

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 and the absence of an output schema, the description is remarkably complete. It explains response contents, compatibility codes, skipped-pairing logic, temporal alignment, low-confidence inspection fields, and the real-world caveat that valid spreads are rarer than the shortcut list implies. An agent has enough context to call the tool correctly and interpret its results.

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

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

The input schema already documents all three parameters with 100% coverage, including the topic list and explicit override semantics. The description adds meaning by explaining the relationship between the two modes, how topic mappings auto-fetch events, and that custom pairings require `kalshi_event_ticker` plus `polymarket_event_slug`. This is genuinely additive, though the schema already provides the baseline parameter meaning.

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

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

The description opens with a clear, specific purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes this from sibling tools by naming the two venues and the spread concept, and it details two operating modes, so an agent can tell what the tool does without inspecting the schema.

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

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

The description explicitly lays out two usage modes: `topic` for 10 pre-mapped macro shortcuts and explicit ticker/slug pairs for custom comparisons. It also warns that pre-mapped topics are not automatically tradeable and that compatibility warnings are common, which gives useful when-to-be-cautious context. However, it does not explicitly contrast this tool with closely related siblings like `polymarket_arbitrage` or `polymarket_edges`, so the alternatives guidance is incomplete.

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, so the safety profile is covered. The description adds behavioral value beyond annotations by revealing that the correct window parameters for a dataset are chosen automatically, that the tool is keyless, and that unrecognized codes are rejected with the full list rather than passed upstream. It also notes some datasets ignore the 'to' parameter and settlement-date datasets require settlement_period. Minor gap: no return-format or pagination details, but the raw-records statement covers the response nature adequately.

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

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

The description is compact and front-loaded: it states the core capability in the first sentence, then gives representative dataset examples, then key behavioral caveats. Every sentence earns its place, and the parenthetical list of examples is information-dense without being padded.

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

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

For a read-only, keyless, schema-rich fetch tool with 100% schema coverage and detailed annotations, the description is complete. It tells the agent what it fetches, from where, how to discover dataset codes, what happens on an invalid code, and the main behavioral exceptions (settlement-date datasets, ignored 'to' parameter). No output schema exists, but 'returns the raw records' is enough given the schema examples already show expected request shapes.

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 every parameter in detail, including examples and requirements. The description adds helpful context by explaining the automatic window-parameter lookup and the special handling of settlement-date datasets, but it doesn't need to explain each parameter syntax because the schema does that. Baseline 3 is appropriate when schema coverage is complete and the description reinforces, rather than extends, parameter understanding.

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

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

The description names the specific verb ('Fetch records'), the resource ('84 Elexon BMRS Insights datasets by its dataset code'), and gives concrete examples (MID, FUELHH, WINDFOR, FREQ, TEMP, REMIT, BOD/BOALF). It distinguishes itself from sibling elexon_list_datasets by explaining that this tool fetches records while that one provides the directory, so an agent can tell them apart without opening the schema.

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

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

The description explicitly says to call elexon_list_datasets to find a dataset code, which routes the agent to the sibling alternative. It also states keyless access and automatic window-parameter selection, telling the agent when no API key is needed and when it does not need to figure out which datetime parameters to pass. This gives clear context for when to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by revealing scoping (anonymous IP, BYO key hash, or account ID), listing behavior when key is omitted, and pairing with remember and forget tools. 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, front-loaded with the primary action. Every sentence adds value: main function, usage context, scoping, and 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?

Given the tool's simplicity (1 optional parameter, no output schema, rich annotations), the description is fully complete. It covers purpose, usage, scope, and relationships to sibling tools, leaving no gaps.

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

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

Schema coverage is 100% with a single parameter 'key'. Description adds crucial context: omitting the key lists all saved keys. This explains behavior not obvious from the schema alone, making the parameter semantics complete.

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

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

Description states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly specifies the verb (retrieve/list) and resource (saved values), and distinguishes from sibling tools 'remember' and 'forget' by explicitly naming them.

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

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

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Provides context for when to use, mentions scoping and pairing with remember/forget. Could add when not to use, but clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details such as the effect of mark_read on subsequent calls ('so the next call only shows newer ones') and the open nature of the feed. No contradictions with annotations.

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

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

The description is a single paragraph that efficiently conveys the main purpose upfront, then expands on details. It is reasonably concise, though a bit dense. Every sentence adds value, and it avoids redundancy with the schema.

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 absence of an output schema, the description compensates by listing the fields returned (source, citation_uri, raw event payload). All 5 parameters are optional and explained in context. The description is complete for a read-only polling tool with straightforward behavior.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema's parameter descriptions. For example, it explains the purpose of mark_read ('flag returned events read so the next call only shows newer ones') and mentions the limit's max (1-200). This extra context helps the agent understand the parameters' real-world 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?

The description clearly states it 'pulls fired events from your subscription feed' and specifies the returned fields (source, citation_uri, raw event payload). This is a specific verb-resource combination that distinguishes it from sibling tools like 'list_subscriptions' or 'subscribe'.

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

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

The description provides context for when to use the tool, including filtering options (type, since) and the mark_read flag. It also mentions that polling works fine and that the same feed is available via an alternative GET endpoint for scripts/dashboards, though it doesn't explicitly state when not to use this tool over alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds details about data sources (SEC, GDELT/GNews, USPTO), fallback logic, date formats, and return structure. 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 dense paragraph but efficiently packs all necessary information. It is front-loaded with examples, though could be slightly more structured with bullet points.

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

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

Despite no output schema, the description explains the return structure (changes[], total_changes, citation URIs). It covers sources, fallbacks, and date handling comprehensively, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, and the description adds value by explaining 'since' formats with examples, noting only 'company' is supported for type, and providing CIK/ticker examples for value. Not critical but helpful.

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 provides a change feed for a company, covering SEC filings, news, and patents. It gives example queries and distinguishes from entity_profile, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool vs. entity_profile, and gives example queries. However, it does not contrast with other sibling tools like deep_research or recall.

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 context about persistence (persistent for authenticated users, 24h for anonymous) and pairing with recall/forget. It could explicitly mention idempotency, but overall provides good 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?

The description is three sentences, front-loaded with purpose, then usage, then behavioral details. Every sentence adds value with no redundancy or fluff.

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

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

Given the simple 2-parameter tool with no output schema, the description covers all necessary aspects: purpose, when to use, behavior details, and relation to siblings. It is fully 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 descriptions for key and value. The description adds naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies that value stores any text. 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?

The description clearly states the tool's purpose: to save data for later reuse across conversations or sessions. It identifies it as a key-value store scoped by identifier, and distinguishes it from sibling tools like recall and forget.

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

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

The description explicitly says when to use the tool: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget, and differentiates behavior for authenticated vs. anonymous sessions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, which cover safety. The description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment, explicit handling of unresolved identifiers instead of omission, source labelling for each identifier, and the internal cascading lookup behavior. It also clarifies that ISIN inputs resolve via a particular mapping, which goes beyond the annotations.

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

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

The description is front-loaded with vivid examples and the key 'Use FIRST' guideline. It is structured into clear sections with `SUPPORTED TYPES`, though it is fairly long. Some phrases like 'cross-source identity spine' are dense jargon but not excessive. Overall, every sentence carries value and the structure aids comprehension, earning a 4 rather than a 5 for its length.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior) and the absence of an output schema, the description is remarkably complete. It explains the return semantics (source-labelled identifiers, unresolved field, RxCUI+ingredient+brand), edge-case behavior (graceful degradation when GLEIF/OpenFIGI unavailable), and internal cascading logic, so an agent can confidently use and interpret results.

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

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

Schema coverage is 100% with both parameters described. The description enhances this significantly by explaining what each type returns (e.g., company resolves to CIK, ticker, LEI, FIGI, and covers non-US issuers; drug returns RxCUI+ingredient+brand). It also expands the 'value' parameter semantics by explicitly listing accepted formats (ticker, CIK, ISIN, name) and giving examples with ISIN resolution details, adding meaning beyond the schema's straightforward enumeration.

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

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

The description clearly states a specific verb+resource: resolve a user-spoken name to canonical/official identifiers. It provides multiple usage examples and explicitly distinguishes its role from other tools by saying 'Use FIRST whenever you have a name but need an ID.' It also differentiates supported types (company vs drug), making it distinct from sibling tools like entity_profile or compare_entities.

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

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

The description gives an explicit when-to-use rule: 'Use FIRST whenever you have a name but need an ID.' It also emphasizes efficiency by replacing 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools for specific scenarios, though the context of siblings and the clear 'Use FIRST' guideline provide sufficient guidance for most cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., and the description adds behavioral details: it probes each entity via ai_visibility_check, ranks results, and returns score/confidence/signal density. No contradiction, and description enriches understanding beyond annotations.

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

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

Two sentences, no wasted words. The main action ('compare AI visibility') is front-loaded. Every sentence adds value, and the structure is clear and 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?

Given 4 parameters, no output schema, but rich annotations, the description covers the tool's purpose, process, output format, and a usage example. It doesn't detail error handling or limits, but that's acceptable for a non-destructive read tool. Nearly 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%, but description adds meaningful context: entities are 'your brand + N competitors', context disambiguates names, _apiKey is for Anthropic model. All four parameters are explained beyond their schema descriptions, leaving no ambiguity.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, distinguishing it from the sibling tool ai_visibility_check which handles single entities. It specifies the verb 'compare' and resource 'AI presence', making the purpose unmistakable.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and gives an example question. It implies when to use (multiple entities) and implicitly when not to (single entity check should use ai_visibility_check), but lacks explicit exclusions.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description details external API fan-out, partial degradation ('sources_failed will list if it times out'), and a performance caveat ('bundlephobia's first measurement can take 5-30s'). 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?

Description is well-structured, starting with the core value proposition, then usage, return details, limitations, and performance caveat. While informative, it could be slightly more concise without losing clarity.

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

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

For a tool with no output schema, the description sufficiently describes return value composition (summary block, per-advisory detail, links, alternative versions). It covers partial failures and ecosystem scope. All necessary context for correct agent invocation is present.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal extra beyond schema: it confirms package accepts scoped packages and explains version defaults, but these are already in schema. The high-level context (checking safety, size) is useful but does not deepen 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?

Description clearly states it's a composite check for npm packages, with specific verbs 'scan' and 'dependency'. It distinguishes from siblings like scan_competitor_ai_presence by focusing solely on npm ecosystem and combining deps.dev and bundlephobia data.

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

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

Explicitly provides usage scenarios: 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes ecosystem limitation ('NPM ecosystem only') and points to alternatives for other ecosystems ('PyPI/Maven... fall under deps.dev:version directly').

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

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

Annotations already declare read-only and idempotent. The description adds valuable behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char limit with truncation flag, and returns character offsets and similarity scores. 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 efficiently written, front-loaded with purpose, and contains no fluff. It is about 100 words but could be slightly more structured (e.g., separate section for technical details). Earns its length.

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

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

Given the tool's complexity, rich annotations, and fully documented parameters, the description is complete. It explains the algorithm, limits, output format (offsets/scores), and pairing advice, with no output schema 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 is 3. The description reinforces schema descriptions but does not add significant new meaning beyond what's in the input schema (e.g., examples for query, default for limit are already in schema).

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verb 'search' and resource 'text'. It provides concrete examples (SEC 10-K, article) and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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: when the record is too big for the prompt. It also suggests pairing with ask_pipeworx_grounded for grounding. However, it does not explicitly exclude alternatives or compare with other search tools.

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

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

Beyond annotations, the description reveals key behaviors: returns subscription ID, delivery channels (feed always on, optional email/sms/webhook with specific constraints), SMS verification requirement, 10/day cap, webhook signing secret returned once, auto-disable after 10 consecutive failures.

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-loading the purpose, then detailing types and delivery. While lengthy, every sentence adds necessary context for complex subscription types. A minor trim could improve conciseness.

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

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

The description covers all three parameters, return value (subscription ID), and delivery details. No output schema exists, but the description adequately explains what is returned. It does not cover error handling or invalid params, but for a tool of this complexity, it is sufficiently 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?

With 100% schema coverage, the baseline is 3. The description adds significant meaning by explaining each enum value with practical examples (e.g., sec_8k items codes, polymarket_edge topics, fred_series series_id) and detailing delivery channel parameters and their constraints.

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 distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains when to use this tool (for live-data event streams), requirements (Pipeworx OAuth account), and provides examples of supported types. It does not explicitly exclude alternatives, but the context is clear.

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

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

Description adds significant behavioral detail beyond annotations: explains that it returns category-bucketed example questions with exact tool+argument shapes from the live catalog. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 single paragraph is packed with information and front-loads purpose. Minor improvement possible with structured formatting, but every sentence earns its place.

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

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

Despite no output schema, the description comprehensively explains return values (categorized questions with tool shapes), covers parameters, usage guidance, and behavioral context. Fully adequate for the tool's purpose.

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% (1 param: topic). The description adds detailed semantics by listing exact topic values (finance, pharma, etc.) and explaining that omitting gives a cross-category spread, going beyond the schema 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 title and description clearly state the tool's purpose as an onboarding entry point that returns categorized example questions with tool suggestions. It distinguishes itself from siblings by explaining it's for learning what Pipeworx can do and lists specific meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing clear when-to-use guidance. It also gives variants: call with no arguments for full spread or with topic to focus.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds the return structure (one row per settlement period) but does not disclose rate limits or authentication needs.

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

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

A single sentence with all essential information, front-loaded with the core purpose. No wasted words.

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

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

For a simple data retrieval tool with two parameters and no output schema, the description adequately explains the return format. Missing details like pagination or limits are minor given the tool's simplicity.

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

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

Schema coverage is 100% with clear descriptions for both parameters (from and to). The description adds no new semantic information beyond confirming the window requirement, so baseline 3 is appropriate.

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

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

The description clearly states that the tool returns Great Britain half-hourly electricity system demand data over a specified datetime window, with specific fields. This verb+resource combination distinguishes it from siblings like generation_by_fuel.

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 specifies the required datetime window, making it clear when to use the tool (for demand data in a time range). However, it does not provide exclusions or alternative tools for other contexts.

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 (destructiveHint: false) align with description. Description adds useful behavioral details: ownership enforcement and soft deletion, which go beyond annotations.

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

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

Two sentences, no fluff. Front-loaded with primary action and constraints.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what the tool does, its side effects, and constraints. 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?

Single parameter 'id' has a schema description. Description does not add further param semantics, but schema coverage is 100% so baseline 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id,' which uses a specific verb and resource. Distinguishes itself from the sibling 'subscribe' tool.

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

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

Explains ownership enforcement ('you can only cancel your own subscriptions') and effect on data ('deactivated, not deleted'). Provides clear context for use, though no explicit alternatives or when-not-to-use are mentioned.

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?

It goes far beyond the annotations by explaining the internal pipeline, the meaning of each verdict, and the critical distinction between could_not_verify and unsupported. It also discloses how tolerance_pct affects results and warns callers not to treat could_not_verify as evidence, which is essential behavioral information.

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

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

The description is long but densely informative, with clear structure: examples, use cases, pipeline details, output semantics, and caller warnings. Each sentence adds value, though it could be slightly tightened without losing context.

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 there is no output schema, the description fully explains return values (verdict enum, grounded value, citation, reasoning) and error handling. It also covers the two major claim categories and the fallback behavior, making it complete enough for an agent to use confidently.

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 describes both parameters, but the description adds valuable semantics: tolerance_pct overrides the claim's implied tolerance, has a bounded range, and is recommended for hallucination detection. The claim parameter's natural-language examples in the schema are reinforced without adding much beyond that.

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 natural-language claim verification service with a specific verb and resource. It also distinguishes between the structured SEC/financial fast path and the grounded pipeline for all other factual claims, making it distinct from generic search or research tools.

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

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

The description explicitly tells the agent when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives granular guidance on financial vs. non-financial claims, but does not explicitly name alternative tools or state clear when-not-to-use conditions.

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