Wikimedia Rest

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

Annotations already cover read-only, open-world, and idempotent hints. The description adds valuable context beyond these: it mentions the default free model, optional paid Anthropic calls with direct billing to the user, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is useful behavioral disclosure not present in annotations.

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

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

The description is three sentences, front-loaded with the core purpose, then key operational details, then return format and use cases. Every sentence adds value with no fluff or repetition.

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

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

Despite having no output schema, the description fully specifies the return format and per-model fields. It covers operational aspects (default model, cost model), parameter semantics (via schema + description), and use cases. This makes the tool's behavior and expectations clear.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it identifies the default model as 'Workers AI Llama-3.3-70b (free)', clarifies the BYO key cost implication, and explains the context parameter's disambiguation purpose. This exceeds schema-only information.

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

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

The description uses a specific verb ('probe') and resource ('LLMs'), clearly stating the tool's function: to score visibility (0-100) per model. It also distinguishes from siblings by focusing on 'AI visibility' scoring rather than query-based tools like ask_pipeworx.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to invoke optional features (default Workers AI model, BYO Anthropic key). However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive hints, so the description only needs to add context. It adds useful behavior: routes to sub-tools, fills arguments, returns cited answers, works on every tier, and is fast. No contradiction with annotations, though it doesn't discuss failure modes or 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?

Dense with high-value content, front-loaded with the 'PREFER OVER WEB SEARCH' directive and clear structure. Some redundancy (repeated mention of 'default entry point') but every section serves a purpose: examples, alternatives, and scope.

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, so the description compensates by stating return format (structured answer with pipeworx:// citation URIs) and use context. It also anticipates follow-up needs (e.g., breaking news). Could mention error behavior or unsupported queries, but is otherwise complete for a complex router tool.

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

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

Schema covers 100% of parameters, but all are just aliases for 'question'; the description adds meaning by explaining the tool itself fills the arguments and providing example queries. This goes slightly beyond the schema's basic alias labels, but the schema already documents the aliases.

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

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

Clearly states it routes questions to 5,564 tools across 1462 verified sources and returns structured answers with citation URIs. Explicitly prefers itself over web search and distinguishes from sibling tools (ask_pipeworx_grounded, deep_research) by their specific use cases.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a wide range of data domains, lists trigger phrases, and gives concrete examples. Tells exactly which alternatives to use for hallucination-resistant answers (ask_pipeworx_grounded) or broad multi-part questions (deep_research).

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it is an experimental edge (candidate routing enabled live), currently identical to ask_pipeworx since no candidate is active, and it is a full working router with no fallback. This goes beyond the annotations without contradiction.

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

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

The description is concise (4 sentences) and front-loaded with purpose, then explains current state and usage. Every sentence contributes meaning—no fluff or redundancy. It is well-structured and informative.

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

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

For a complex router tool with 5,564 tools and no output schema, the description is complete: it clarifies the beta nature, current behavior (matches stable), and usage. It omits details like response format, but that is consistent with ask_pipeworx and likely understood from the sibling context. The description covers the essential aspects.

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 each parameter (question and its aliases) well-documented. The description adds no additional parameter semantics, but with full schema coverage, baseline 3 applies and this is adequate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tool set, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by noting candidate routing improvements are tested live, and explicitly says it currently matches ask_pipeworx exactly.

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 directs 'Use it exactly like ask_pipeworx when you want the newest routing', and implies ask_pipeworx is the stable alternative. It also explains that results are compared against the stable router, giving context for when to choose it. However, it does not explicitly contrast with ask_pipeworx_grounded, though that may not be necessary.

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 exact success and failure return shapes, including refusal reasons, evidence extraction, and the extra LLM call cost. This goes well beyond the annotations, which already indicate read-only, idempotent, and non-destructive behavior. No contradiction exists between description and 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 its core value proposition and uses a compact structure to pack in success shape, refusal reasons, use cases, sibling differentiation, and cost tradeoff. Every sentence adds operational value and none is redundant.

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 fully specifies the return contract and refusal semantics. It also covers when to use grounded mode vs. the lighter sibling, making the tool self-sufficient for an agent to select and invoke correctly in high-stakes contexts.

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

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

The input schema has 100% description coverage, with all aliases (q, text, input, query, prompt) documented. The description does not add parameter-specific semantics, but the schema already fully explains the question parameter, 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 this as a grounded, hallucination-resistant answer mode: it routes like ask_pipeworx, fetches from tools, and extracts answers using only the tool result. The scope and unique behavior are explicit, and it clearly distinguishes itself from ask_pipeworx.

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

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

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. It also names the alternative (ask_pipeworx) and describes the cost tradeoff, which fully satisfies the when-to-use vs. alternatives criterion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description extensively details edge-case behavior: low-confidence resolution short-circuiting, closed-market status, liquidity spread warnings, cancellation-rule risk parsing, and news fallback mechanics. These disclosures far exceed what annotations provide.

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

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

The description is lengthy but every section earns its place—classifiers, fan-out examples, response shapes, resolver contract, and safety rules are all directly actionable. Front-loaded with the core purpose, the structured headings make it navigable.

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 and complex behavior, the description covers all major aspects: input variants, classification, fan-out, response structure, match confidence, parent-event extraction, news fallbacks, and safety/risk behaviors. It leaves no critical gap.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds illustrative examples for `market` and clarifies fan-out behaviors for `depth`/`include_raw`, but does not fundamentally augment the structured 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 verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling Polymarket tools by emphasizing the one-call fan-out to category-specific data packs and the market-vs-model comparison.

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

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

Explicit 'Use for...' phrases define the intended scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It does not explicitly mention when-not-to-use or alternative tools, but the rich fan-out examples and classifier list provide strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description consistently describes read-only data pulls. It adds substantial behavioral context: sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output includes citation URIs. No contradictions.

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

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

The description is dense but every sentence carries information: query examples, preference over alternatives, data sources, fiscal year handling, sorting behavior, output format, and efficiency gains. It is front-loaded with usage examples and remains appropriately sized for a tool with two entity types and multiple data sources.

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 data sources, sorting, output with citations), the description covers all essential aspects: when to use, what data is pulled per type, how results are sorted, and what output includes (paired data + pipeworx:// URIs). No output schema exists, so the description's explanation of return values is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what each type parameter does (company pulls 10-K financials, drug pulls FAERS/trial counts) and gives concrete examples for values (tickers/CIKs, drug names). This goes beyond the schema's enum descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, with concrete trigger phrases ('compare X and Y', 'which is bigger') and distinguishes from sequential lookups by claiming to replace 8–15 of them. It also differentiates from sibling entity_profile by explicitly targeting multi-entity comparisons.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides examples of when to use it (comparison queries, ranking, head-to-head). It gives guidance on choosing type='company' vs type='drug', and implies not to use for single-entity lookups. This is clear usage direction with alternatives.

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

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

Annotations already cover readOnly/openWorld/idempotent, and the description adds rich context: account sign-in requirements, parallel routing, gaps[] for unanswered facets with 'never invented', contradictions[] scanning, semantic excerpting of large records, and expected latency. No contradiction with annotations; the description adds substantial value beyond 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 (~250 words) but every major section earns its place: auth, main purpose, alternatives, depth behavior, return format, timing. It is structured with logical transitions and concrete examples, though slightly dense; no significant redundancy.

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

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

With no output schema, the description must explain return values, and it does thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers timing, account requirements, and depth variants, making it fully complete for a 2-param tool.

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

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

Schema covers both parameters at 100%, so baseline is 3. The description adds operational meaning by explaining depth's effect on facet count/hops and that 'thorough' requires a paid plan, plus clarifying that the question can be broad/natural language. This extra context justifies a 4.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and decomposes questions into facets, making the purpose unmistakable. It also distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and naming ask_pipeworx as the alternative for different use cases.

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

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

Explicit when/when-not guidance: 'Best for broad/multi-part questions over structured data' and for single lookups or breaking news 'use ask_pipeworx'/'prefer ask_pipeworx'. It also covers account-tier constraints, telling agents to use ask_pipeworx if not signed in, which is actionable and clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral value by explaining the return format: top-N tools with names, descriptions, and full input schemas, and notes that results are ready to call directly without a second schema lookup. This goes beyond what annotations provide, though it doesn't detail edge cases or failure behaviors.

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

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

The description is front-loaded with the core purpose and then provides necessary context. The list of domains is long but serves as a concrete scope indicator. The sentence about 'full input schemas (with curated examples)' is informative and earns its place, though the description could be tightened slightly without losing meaning.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description does a good job of explaining what the agent will receive: names, descriptions, and full schemas. It also covers use cases and ordering. It doesn't explain pagination or errors, but the limit parameter and straightforward nature of the tool make this acceptable.

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

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

Schema coverage is 100%, so the baseline is 3. The description references 'query' and 'top-N' which maps to the query and limit parameters, but it adds little beyond what the schema already says. The aliases are documented in the schema, and the description's mention of 'top-N' reinforces limit but doesn't add new semantics.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a meta-tool for discovering other tools, which is unique among the sibling tools. The scope is further clarified with a long list of domains, leaving no ambiguity about what the 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?

Explicit usage guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to invoke this tool, positioning it as a first-step discovery tool rather than a direct answer tool.

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

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

While annotations already declare read-only and idempotent, the description adds substantial behavioral context: parallel fan-out across sources, return format details (e.g., URIs, sorted fundamentals), fallback chain (GDELT→GNews), and soft-failure for the USPTO PatentsView sunset. These are not inferable from annotations and enhance transparency.

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

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

The description is dense but every sentence earns its place: trigger phrases, preference guidance, data sources, return fields, param constraints, and failure mode. Structured with semicolons and bullets-like clauses, it packs needed detail without filler.

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

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

No output schema exists, so the description must explain return values—it does, listing all output fields and even edge-case behavior (patents soft-fail, fallback). For a complex multi-source tool, this is fully adequate for an agent to understand what it will receive and what limitations may apply.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the ticker/CIK guidance already in the value param description ('use resolve_entity first if you only have a name') but adds no new parameter meaning beyond the schema. No extra credit 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?

Description states its specific function: "full cross-source profile of a US public company in ONE parallel call." It details the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and output fields, and explicitly differentiates from siblings by saying "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups" and referencing resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use: "ALWAYS PREFER ... when the user asks for a holistic view." Also provides when-not-to-use and alternative: "names not supported (use resolve_entity first if you only have a name)." This clearly guides selection among siblings like resolve_entity, compare_entities, and deep_research.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds value by specifying the exact content components returned (featured article, most-read, picture of the day, on-this-day events), giving a concrete sense of the tool's output without contradicting annotations.

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

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

The description is two sentences with no filler. The first sentence defines the tool's purpose and scope, and the second offers concrete use cases. It is front-loaded and every word earns its place.

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

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

The tool is read-only and has a strong output schema, so the description need not explain return values. It adequately conveys purpose and usage, but the lack of parameter explanations for lang/project means the description is not fully self-sufficient for a 5-parameter tool.

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

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

Schema description coverage is 0%, and the description only references the date components ('specific date') without explaining the purpose of lang or project. The parameter names and examples provide some hints, but the description does not compensate for the lack of schema descriptions, leaving the agent to infer the semantics of language and project parameters.

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

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

The description clearly states the tool returns Wikipedia's 'today's featured' content for a specific date, enumerating the content types (featured article, most-read, picture of the day, on-this-day events). This distinguishes it from siblings like onthisday and random, which focus on narrower scopes.

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: 'what's on Wikipedia today', 'featured article on 2026-05-21', and 'to seed daily-roundup content'. It gives clear context for when to invoke the tool, though it does not mention exclusions or 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 destructiveHint=true and idempotentHint=true, so the description does not need to restate those. It adds valuable context by clarifying what gets destroyed ('previously stored memory' and 'sensitive data'), which goes beyond the structured annotations. No contradictions found.

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

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

Two sentences, no filler. The first sentence front-loads the action, the second provides usage context and alternatives. Every word earns its place.

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

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

For a simple deletion tool with one parameter and no output schema, the description is complete: it states what it does, when to use it, and related tools. The idempotentHint annotation covers the missing-key edge case, so no additional operational details are 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 description coverage is 100% for the single 'key' parameter, so the schema already fully explains it as 'Memory key to delete.' The tool description adds no additional parameter detail beyond the word 'key', thus falls at the baseline for high schema coverage.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It uses a specific verb ('Delete') and resource ('memory by key'), and distinguishes itself from sibling tools like 'remember' and 'recall' by its management role.

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

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

It provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also directly references alternatives with 'Pair with remember and recall,' giving clear guidance on when to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by explaining the internal process (fetching, extracting, emitting) and the output format ("a single text blob ready to drop at site-root/llms.txt"). This provides transparency about how the tool operates and what the result looks like, 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 three sentences, each adding distinct value: the first states the core purpose, the second explains the process, and the third lists relevant use cases. There is no fluff, repetition, or unnecessary detail, making it efficient and well-structured.

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

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

With no output schema, the description appropriately explains the return value ("Output is a single text blob"), and it covers the key contexts (who it's for, why you'd use it). It also includes concrete examples of intended use, making the tool's role within the broader tool set clear. Given the simple 2-parameter schema and strong annotations, the description 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?

The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds minimal semantic value for parameters: it mentions 'any URL' which aligns with the url parameter, but does not clarify max_links behavior beyond what the schema already provides. Since schema already does the heavy lifting, this is adequate but not enhanced.

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

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

The description clearly states the tool's purpose: "Generate a production-ready llms.txt file for any URL" and elaborates on the process ("Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format"). This distinguishes it from sibling tools like page_summary or scan_competitor_ai_presence by focusing on llms.txt generation rather than generic summarization or AI presence analysis.

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

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

The description provides explicit use cases: "getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor." This gives clear context for when to use the tool, though it does not explicitly mention when NOT to use it or name alternative tools, missing the full 'when-not' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable behavior beyond that: it returns a specific set of fields and lists only active subscriptions by default. This gives the agent a clear picture of what to expect from the response without an output schema.

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

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

The description is two sentences long and front-loaded: the first sentence states the action and return shape, the second gives usage context. Every word earns its place, with no repetition of schema or annotation details.

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

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

This is a simple read-only list tool with one optional parameter and strong annotations. The description covers the tool's core purpose, return fields, and when to use it, making it fully self-sufficient even without an output schema.

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

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

The input schema has 100% coverage for the single optional parameter include_inactive, with a clear description in the schema itself. The tool description does not add extra meaning to the parameter, but since the schema already documents it well, the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions,' specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe, making the tool's 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 usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke this tool and implicitly contrasts with subscribe/unsubscribe for other actions. The mention of 'active subscriptions' also clarifies that include_inactive can widen the scope.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, lowering the bar. The description adds value by explaining the different content types returned and that results are for any month+day. It does not contradict 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 compact, front-loaded with real-world queries, and uses a dash-separated list to enumerate content types. Every phrase adds useful information, with no redundant or filler 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 an output schema exists and annotations are strong, the description covers the essential purpose and filtering behavior. It could mention that 'lang' and 'project' are optional, but this is a minor gap. Overall it is sufficiently complete for a simple read-only lookup tool.

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

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

Schema coverage is only 20%, so the description must compensate. It does explain the 'type' values, matching the schema's own description, and implies month/day are numbers. However, it does not explain optional parameters like 'lang' and 'project', which are only shown in examples. This is a partial but not complete compensation.

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 natural language queries that clearly define the tool's function: retrieving historical events for a given date. It enumerates the types of occurrences (births, deaths, events, holidays, selected) and distinguishes it from other sibling tools that focus on pages or 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?

It provides explicit usage instructions for the 'type' parameter ('Pass type="all" for everything, or filter to...'), which gives clear guidance on filtering. However, it does not mention when to prefer this tool over alternatives, so it stops short of a full 'when-to-use' explanation.

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 clear. The description adds behavioral context by specifying Parsoid-rendered HTML and that the output can be scraped/parsed, which is useful beyond the annotations. No contradiction is present.

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

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

The description is two sentences, front-loaded with the core function, and every phrase carries value. It avoids redundancy and is appropriately sized for the tool's simplicity.

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 a simple read-only fetch, and the output schema is present, so the description needn't detail return fields. It communicates the return type (rendered HTML) and the use case. The main gap is parameter semantics, but the context is otherwise sufficient for an agent to select and invoke the tool.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter explanations. It only implicitly references the article title (via 'Full Wikipedia article HTML') but does not clarify the meaning of 'lang' or 'project'. This forces an agent to infer the expected values, which is insufficient for a 3-parameter 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 fetches full Wikipedia article HTML (Parsoid output) and explicitly distinguishes it from page_summary by noting it provides complete article body, infoboxes, tables, and embedded content. The verb and resource are specific and unambiguous.

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

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

It provides explicit when-to-use guidance: 'use when page_summary's extract isn't enough' and names the alternative tool (page_summary). It also describes what content is included, which helps an agent decide. However, it lacks an explicit when-not-to-use phrase or mention of other alternatives like page_media or page_pdf, so it stops short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety aspects. The description adds scope (embedded media, Commons-hosted material) but does not disclose potential limitations like return format or size constraints. Given the annotation coverage, this is an adequate but not exceptional contribution.

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, with two sentences: a clear definition and practical usage examples. No unnecessary words, and it is front-loaded with the core purpose.

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

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

With an output schema present and annotations covering safety, the description sufficiently conveys the tool's purpose and usage. The main gap is the lack of parameter explanation, but for a relatively simple tool with output schema, the description is reasonably complete.

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

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

Schema description coverage is 0%, and the description does not explain any parameters. It implies 'title' through 'Wikipedia article' but leaves 'lang' and 'project' entirely unaddressed. The description fails to compensate for the missing schema descriptions, offering little additional meaning beyond the parameter names.

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's function: retrieving images, videos, and other media embedded in Wikipedia articles. It provides specific example queries ('show me pictures of X') and distinguishes it from sibling page_* tools by focusing on media content rather than text or metadata.

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 clear usage examples and context, such as queries about images on a page or Commons-hosted media. However, it does not explicitly state exclusions or compare with alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by enumerating the exact metadata contents returned (categories, links, URLs, page_id, namespace) and stating the intended applications, which goes beyond what the annotations alone convey.

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

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

The description is two sentences and every word earns its place. The first sentence immediately states what the tool returns, and the second sentence provides concrete use cases. No filler or redundancy.

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

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

With an output schema present, the return structure is already defined. The description covers the core purpose, the specific metadata fields, and practical use cases. This is fully complete for guiding an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters (title, lang, project). While 'title' is self-evident from the examples, 'lang' and 'project' remain ambiguous. The description fails to compensate for the lack of schema documentation, making it unclear what values these parameters accept or how they affect the output.

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 statement of what the tool returns: 'Wikipedia article metadata' and lists the specific fields (categories, inter-language links, content_urls, page_id, ns). It further clarifies the purpose with three concrete use cases: 'get canonical IDs, discover language versions, or check which categories an article belongs to.' This distinguishes it from sibling tools like page_summary or page_html.

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 with 'Use to...' which signals when to choose this tool over alternatives. It does not explicitly name alternatives or mention when not to use it, but the specificity of the listed use cases gives clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds valuable behavioral context by explaining that the tool returns a URL and that the caller must fetch the binary PDF directly via browser or curl, making the two-step nature explicit. This goes beyond the annotations and helps the agent know the output is not the PDF itself.

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 extremely concise, using only two sentences to convey the core functionality and required next step. It front-loads the main action and avoids any fluff or repetition. The structure is efficient and easy 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?

The tool is relatively simple, and the output schema exists, but the description leaves gaps. The 'project' parameter is ambiguous, and the 'Mapbox static-tile image URL' wording is opaque. The description does not explain the relationship between the URL and the PDF, nor does it clarify the values for 'project' or 'lang'. Given 0% schema description coverage, the description should have provided more detail to make 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 description coverage is 0%, so the description must compensate. It adds some meaning by stating that title is required and that project/lang are optional for non-English Wikimedia projects, which helps clarify their role. However, it does not thoroughly explain the format expected for 'project' (e.g., 'wikipedia' vs 'wiktionary') or how 'lang' should be specified, leaving ambiguity for an agent trying to invoke the tool correctly.

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 that the tool returns a URL for a PDF download of a Wikipedia article, using the verb 'Returns' and naming the resource. It also distinguishes itself from sibling page_* tools by being the only one that returns a PDF download URL. However, the phrase 'Mapbox static-tile image URL' is confusing and could mislead about the actual output format.

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 implicit usage context: it is for retrieving a PDF of a Wikipedia article, and it mentions optional project/lang for non-English projects. It also instructs the caller to fetch the PDF from the returned URL, which is a clear usage step. However, it does not explicitly state when to use this tool versus alternatives like page_html or page_summary, nor does it provide any 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral context by explaining that the tool retrieves cited sources and suggests it is a read-only retrieval operation. 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 two sentences, front-loaded with the core function, and every phrase earns its place. It efficiently communicates purpose and usage 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?

The tool is simple and has an output schema, but the complete lack of parameter documentation in both the schema and description leaves a gap for users unfamiliar with the 'lang' or 'project' fields. The description covers purpose and usage well, but not enough to be fully self-contained.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain 'title', 'lang', or 'project'. The example query implies 'title' refers to a Wikipedia article, but the parameter names are not explicitly clarified. The description adds marginal value beyond the bare 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 returns citations/references/sources cited by a Wikipedia article. It uses a specific verb-noun structure and provides concrete example queries like 'what sources back the claim that...' which distinguish it from sibling tools such as page_metadata or page_summary.

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 usage contexts through example questions and intents (e.g., harvesting authoritative external links). It does not explicitly name alternatives or exclusions, but the examples make it clear when to reach for this tool over siblings.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds behavioral detail by stating returns up to ~12 related pages with summaries, which goes beyond the structured 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 two sentences: the first front-loads the purpose with a clear metaphor ('see also'), and the second adds use cases. Every word earns its place, with no repetition of schema 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?

Given the tool's simplicity, the output schema likely covers the return structure, and annotations cover safety. The description covers purpose, usage, and return details, but lacks parameter semantics and edge-case behavior, which prevents a perfect score.

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 0%, and the description does not explain lang or project parameters. It only implies title via 'any topic' and the example 'Isaac Newton', leaving optional parameters undefined.

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 explicitly states it returns Wikipedia's related-articles graph with summaries for any topic. This clearly distinguishes it from sibling page_* tools like page_summary or page_metadata by naming the specific function ('related articles') and resource (Wikipedia).

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

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

Provides explicit use cases: 'what should I read next', topic exploration, or finding adjacent concepts. It does not name alternatives or exclusions, but the context is clear enough to decide when to use it.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that the history is 'recent' (a scoping constraint) and specifies the data fields returned, which is useful context beyond the annotations. No contradiction with annotations.

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

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

Two concise sentences front-load the tool's purpose and data content, followed by practical use cases. Every word contributes, with no fluff or repetition.

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

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

The description covers purpose, usage, and some output details, and annotations cover safety. However, the lack of parameter descriptions for lang/project and any mention of limits (e.g., number of revisions returned) leaves the tool slightly incomplete, though the output schema may mitigate the return-value gap.

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 0%, and the description only implicitly covers the 'title' parameter via 'Wikipedia article.' It does not explain 'lang' or 'project' parameters, leaving the agent without necessary context for those inputs.

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

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

The description clearly states 'Recent edit history for a Wikipedia article' and lists specific data elements (editor usernames, timestamps, revision sizes, edit comments), which precisely defines the tool's function and distinguishes it from sibling tools like page_summary or page_metadata.

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: 'Use to check when an article was last updated, spot recent disputes, or assess reliability before quoting.' However, it does not explicitly mention when not to use the tool or name alternatives, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavior: defaulting to en.wikipedia.org, supporting project/lang overrides, and returning specific fields (thumbnail, lead paragraph). This goes beyond the structured 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 compact yet packed: trigger phrases, purpose, usage guidance, defaults, and an example are all covered in two sentences. Every clause earns its place with 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 read-only summary tool with an output schema, the description fully covers the common use case, including language/project options and an example. Return format is already documented by the output schema, so no further detail is needed.

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

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

Schema coverage is 100% so the baseline is 3. The description adds meaning by explaining the default project/lang behavior and giving a concrete example (page_summary({ title: "Albert Einstein" })), which shows how parameters combine beyond the schema descriptions.

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

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

The description explicitly states "fetches the Wikipedia article extract (title, description, thumbnail, lead-paragraph extract)", giving a specific verb and resource. It distinguishes this from siblings like page_html or page_media by focusing on the summary extract rather than full content or media.

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 provides a clear usage context: "Use whenever an agent needs a quick encyclopedic reference" and gives example query phrases. However, it does not explicitly contrast with alternative sibling tools like page_metadata or page_revisions, so it stops short of full when-not guidance.

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

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

With no behavioral hints from annotations (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false), the description takes full responsibility. It discloses the claim_token flow, rate-limiting ('Rate-limited to 5 per identifier per day'), non-quota usage ('doesn't count against your tool-call quota'), and expected processing cadence ('team reads digests daily'), which goes beyond the minimal and is highly informative 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 front-loaded with purpose, then usage, exclusions, and behavior. Every sentence carries necessary information: when to use, when not to use, how to frame content, claim-token mechanics, rate limits, and quota note. Despite length, it is dense and efficient, with no filler or 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?

The description is fully self-contained for an agent to decide, invoke, and handle results correctly. It covers output behavior (claim_token generation, later retrieval), rate limits, scope constraints, and content guidance. No output schema exists, but the description sufficiently explains what to expect, so the agent won't be surprised.

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

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

Schema coverage is 100% for the four parameters, so baseline is 3. The description adds semantic value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), and ties the context object to 'Pipeworx tools/packs'. This enriches parameter understanding without duplicating schema detail.

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

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

The description uses a specific verb ('Tell the Pipeworx team') and resource ('something is broken, missing, or needs to exist'), clearly defining the tool's purpose. It distinguishes from sibling tools (which are for research/info) by framing this as feedback submission, with explicit types (bug, feature, data_gap, praise).

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

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

Provides explicit when-to-use guidance for each feedback type and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' It also clarifies the scope (Pipeworx tools/packs) and instructs not to paste end-user prompts, giving clear usage boundaries.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses caching, data source, aggregation, and privacy aspects 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 well-structured and front-loaded: a one-sentence summary, followed by a returns list, three numbered use cases, and a concise note on aggregation/caching. Every sentence earns its place, 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?

For a tool without an output schema, the description adequately explains the return content ('top tools, top packs, and total call volume') and even hints at the data shape ('just (pack, tool, count)'). It does not specify the exact JSON structure, but for a simple trending endpoint this is a minor gap.

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 with a clear enum description: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' The main description only lists the window options without adding further semantic nuance, so it does not exceed the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This uses a specific verb ('Returns') and resource, and distinguishes it from siblings like `discover_tools` by focusing on current trending behavior.

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 sources, confirming canonical tools, and alignment with agent needs. However, it does not name alternatives or state when not to use this tool, so it falls short of the 'explicit when/when-not/alternatives' standard, 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals internal behavior: Jaccard similarity threshold of ≥0.30, placeholder filtering with >20% threshold, 3pp partition deviation trigger, fill check against live CLOB depth, and the warning 'realizable_edge_pp ≤ 0 means... do not trade it.' It also discloses response fields. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with purpose. Most sentences earn their place with valuable details (mode distinctions, semantic anchor, partition filter, response format, fill check). However, it could be slightly tighter; some details like exact thresholds might be better in schema or output schema if present. Still, appropriate for a complex tool.

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

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

For a tool with three modes, optional params, and no output schema, the description is remarkably complete. It covers invocation patterns, internal checks, response shape, critical caveats (fill check, do not trade), and references to sibling tool polymarket_fill_risk for custom sizing. Given the complexity, all necessary context is provided.

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 descriptions for 'event' and 'topic' are present (100% coverage), but the description adds significant meaning: event slugs examples, full Polymarket URLs accepted, topic seed question examples, and mode-specific behaviors. It clarifies what each parameter controls and how they differ, adding 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_fill_risk by explicitly directing custom sizing to that tool, and from polymarket_edges by focusing on arbitrage scanning. The three invocation modes (no args, event, topic) are clearly explained.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It includes examples of event slugs and topic seeds, explains when event vs topic is appropriate, and explicitly names an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is model usage guidance.

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

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

No annotation contradiction exists; annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds extensive behavioral detail: model logic, slippage assumptions, Kelly caps, placeholder-slug filters, rare-by-design gating, a 24-hour move warning, diagnostics, and 1-hour KV caching. This goes far beyond the annotations and discloses important caveats for safe use.

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

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

The description is dense and well-structured with clear section labels, but it is quite long and redundantly repeats some parameter choices that already have detailed schema descriptions. Given the tool's complexity, the length is largely justified, but a tighter pass could remove a few parentheses and repetitions.

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 takes on the burden of explaining return values, and it does so thoroughly: top-level by_segment structure, per-opportunity fields, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers why segments may be empty and how knobs affect results, making it complete for agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics for tradeable-edge knobs (min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable') and explains why min_partition_leg_kelly is needed since partition arbs return kelly_fraction_half=0 at the parent level. Not all parameters receive narrative beyond schema, but the added context is meaningful.

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 verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further frames the tool as 'what should I bet on today' and enumerates three model segments, making the scope unambiguous and differentiating it from sibling tools.

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

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

It provides a clear intended use case ('what should I bet on today' and 'agents discover opportunities without paging hundreds of markets'), plus contextual notes about Fed bets and filter knobs. However, it does not explicitly mention when to prefer sibling tools like polymarket_arbitrage or polymarket_edge_tracker over this one.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses TTL limits, snapshot gap behavior, the computation basis (daily closes, net slippage), and what missing dates mean. This significantly enhances an agent's understanding of data caveats—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 dense but well-structured into Args, RESPONSE, and LIMITS sections, making it easy to parse. Every sentence earns its place, and the core purpose 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?

Despite no output schema, the description meticulously defines all response fields, their semantics, and edge cases like expired opportunities and snapshot gaps. It even provides interpretive guidance (median lifespan as competition clock). Highly complete for the tool's complexity.

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

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

Schema already describes both parameters with defaults and ranges, so description adds little beyond restating 'lookback' and 'snapshot family.' With 100% schema coverage, 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's function: tracking edge persistence and decay across daily snapshots. It distinguishes itself from the sibling polymarket_edges by focusing on historical trend rather than current values, answering a specific question about edge freshness.

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

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

Provides strong contextual guidance with the example of fresh vs. old edge meaning, implying use cases. However, it does not explicitly name alternatives or state when not to use this tool (e.g., when current edges are needed, use polymarket_edges), so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower. The description adds operational detail: it walks the order-book ladder, calculates both top-of-book and VWAP fill prices, returns per-leg detail in basket mode, flags thin legs, and warns about forced directional risk from partial fills. This substantially exceeds what annotations alone convey; no contradiction exists.

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

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

The description is long but information-dense, with each clause adding a distinct fact. It avoids filler and front-loads the core purpose. However, the single dense paragraph could benefit from bullet-structured separation of single-market vs basket modes for scannability, so a 4 rather than 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?

For a tool with two operation modes, four parameters, no output schema, and significant risk implications, the description covers all bases: mode selection, parameter meanings, expected outputs, and critical usage timing. It even names the dominant loss mode. There is no obvious missing 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?

Even though schema coverage is 100%, the description enriches meaning: it explains that size_usd is interpreted as max spend for buys, target proceeds for sells, and as settlement notional S (shares per leg) in basket mode. It also clarifies the default auto side selection for baskets and the clamp range. This is contextual information not present in the schema.

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

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

The description opens with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', naming the exact operation and distinguishing it from sibling tools like polymarket_arbitrage that identify edges. It then enumerates concrete outputs (vwap_fill_price, slippage_pp, verdict) that make 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?

Explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming exact sibling tools and providing a threshold. It also explains the failure mode it prevents, giving when-not-to-skip guidance. No alternative is needed beyond this clear directive.

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 goes far beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). It explains the safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and their meaning, discloses that most pre-mapped topics are not tradeable, and clarifies how the tool behaves when bet shapes are non-equivalent. This is a rich behavioral disclosure that helps the agent anticipate edge cases and limitations, with no contradiction to the annotations.

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

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

The description is long but well-structured into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a final caveat. Each sentence adds meaningful information, and the structure makes it easy to scan. It could be slightly more concise by trimming some explanatory prose (e.g., the participant pools analogy), but it remains efficient for the complexity it covers, earning a strong 4.

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 takes full responsibility for explaining the response: it mentions leg-by-leg prices, top_spreads_pp, compatibility_warning with two specific cases, and temporal_alignment. It also covers the tool's limitations and the meaning of skipped cross-type/subtype counters. For a tool with 3 optional params and no output schema, this is a thorough and complete description that leaves little ambiguity for the 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?

Although the schema already has 100% coverage with descriptions for all three parameters, the description adds significant meaning by explaining the relationship between them: the 'topic' parameter is a pre-mapped shortcut, while the explicit parameters override the mapped sides. It also provides concrete examples (e.g., 'fed', 'KXFED-26OCT', 'fed-decision-in-june-825') and clarifies how modes interact, giving the agent a deeper understanding of how to invoke the tool correctly.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb (compute), resource (two venues), and scope (same resolving question). It also distinguishes itself from siblings like polymarket_arbitrage by emphasizing the cross-venue nature and the two modes (topic shortcuts vs explicit pairing), making its 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 clear context for when to use the tool: to compare prices between Kalshi and Polymarket, with two modes (topic shortcuts and explicit overrides) explained. It also gives important usage warnings, such as 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility warnings, effectively telling the agent when not to trust the output. However, it does not explicitly name alternative tools or say 'use this instead of X', so it stops short of a full when/when-not/alternatives breakdown.

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, so the safety profile is covered. The description adds behavioral context by noting the random selection and that the output matches page_summary, which goes beyond the annotations and helps set expectations.

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

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

The description consists of two sentences, front-loaded with the core action ('Random Wikipedia article summary'). Every sentence adds value: purpose, use cases, and output format, with no filler or 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?

The tool is simple and the annotations plus mention of page_summary's shape cover safety and return format reasonably well. However, the optional lang/project parameters are not explained, and there is no mention of alternatives, creating a minor completeness gap. It is adequate but not fully 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?

The input schema has two parameters (lang, project) with zero descriptions, and schema description coverage is 0%. The description does not mention these parameters at all, leaving their meaning and purpose undefined for the agent. This is a clear gap that is not compensated.

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 picks a random Wikipedia article summary with a specific verb ('pick a random article') and identifies the resource (Wikipedia article). It distinguishes itself from sibling tools like page_summary or featured by emphasizing the random selection and the summary return shape.

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 lists use cases ('give me a random Wikipedia article', 'surprise me', or seeding exploration), which tells the agent when to invoke this tool. It does not mention alternatives or when not to use, but the provided context is strong enough for basic scenario selection.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds valuable behavioral context: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving versus listing. 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?

Three sentences, front-loaded with the core action, and every clause earns its place. It efficiently communicates the operation, usage scenarios, scoping, and related tools without repetition or filler.

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

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

For a simple tool with one optional parameter and strong annotations, the description covers the main behaviors, scoping, and sibling relationships. It doesn't specify return format or missing-key behavior, but the absence of an output schema makes that less critical; the description is sufficient for correct invocation.

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% for the single optional 'key' parameter, so the baseline is 3. The description adds extra semantic detail by giving concrete examples of stored content (target ticker, address, research notes) and reinforcing the omit-key-lists-all behavior, which goes beyond the schema.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes the read/lookup nature of recall from sibling tools remember and forget, which write and delete.

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 scenarios for use ('look up context the agent stored earlier'), states when to omit the key for listing all keys, and mentions pairing with remember/forget. It does not explicitly state when not to use it, but the context is clear enough for an AI agent to decide.

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

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

The annotations declare readOnlyHint: true, but the description explicitly describes a state-mutating behavior: 'Set mark_read:true to flag returned events read.' This directly contradicts the read-only hint, creating an annotation contradiction. Although the description adds valuable context about feed contents and polling, the contradiction undermines trust and earns a score of 1.

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 long, front-loaded with the verb and resource, and includes no filler. It concisely packs in output format, filtering options, the mark_read side effect, polling suitability, and an alternative endpoint. The extra detail about the evaluator and the direct feed URL is useful and earns it a 4 rather than 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?

For a tool with 5 optional parameters and no output schema, the description is exceptionally complete. It specifies the return format (source, citation_uri, raw event payload), explains filtering semantics, describes the read-state mutation, and notes polling behavior plus an alternative HTTP endpoint. This gives an AI agent everything it needs to select and invoke the tool correctly.

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

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

The input schema already documents all 5 parameters with clear descriptions, giving 100% coverage. The description adds a concrete example for type ("sec_8k") and clarifies the effect of mark_read on subsequent calls, but these are minor enhancements over the schema. With the schema carrying most of the semantic weight, a 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly defines the tool's scope (recent alerts written to a persisted feed) and differentiates it from siblings like list_subscriptions or recent_changes by focusing on fired alerts. The mention of the raw event payload and citation_uri further pinpoints the functionality.

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 practical usage context: how to filter by type and since, how to use mark_read for incremental reads, and a note that polling works fine. It also offers an alternative access method (direct GET endpoint) for scripts and dashboards. While it doesn't explicitly state when not to use this tool, the guidance is clear and actionable for most scenarios.

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?

With annotations already declaring read-only, idempotent, and open-world, the description adds substantial behavioral context: fan-out across SEC EDGAR, GDELT→GNews fallback with rate-limit handling, USPTO soft-fail due to API sunset, and parallel execution. It also describes the return structure (changes[] grouped by source, total_changes count, citation URIs), going well beyond the annotations.

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

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

The description is long but information-dense, with front-loaded examples that aid intent matching. While efficient, the initial example list is somewhat redundant and could be trimmed, but every subsequent sentence earns its place by covering sources, fallbacks, output, and alternatives.

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 fully documents return values (changes[], total_changes, citation URIs) and covers edge cases like GNews fallback and USPTO sunset soft-fail. It also provides a clear alternative tool, making the description complete for the tool's complexity.

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

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

Schema coverage is 100% with each parameter (type, since, value) having descriptive text. The description adds only a minor recommendation ('Use "30d" or "1m" for typical monitoring') and repeats the schema-provided formats. Given the high schema coverage, the description adds little new parameter-level meaning, hence a 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?

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific verb ('change feed') and resource scope (company). It distinguishes from sibling by explicitly naming 'entity_profile' as the alternative for static profiles, and lists concrete example queries that map to user intents.

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 through examples ('What's new with X') and states an alternative: 'Use entity_profile instead when you want the static profile...'. It also explains the time-window context and that this is for dynamic changes, not static data.

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 persistence details beyond annotations: key-value pair scoped by identifier, 24-hour TTL for anonymous sessions, persistent for authenticated users. It does not contradict annotations (idempotent, non-destructive). Minor omission: no mention of overwrite behavior when saving an existing key.

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: one purpose sentence, one usage sentence, and one technical sentence. It is front-loaded with the primary action and avoids fluff.

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

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

For a simple 2-parameter write operation with annotations covering idempotence and non-destructiveness, the description covers all essential operational context: what to save, when, persistence behavior, and companion retrieval/deletion tools. No output schema is needed for this tool.

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

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

Schema coverage is 100% with descriptive parameter docs for key and value. The description reinforces the key-value pairing but adds no new syntax or format details beyond the schema, meeting the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from siblings by explicitly pairing with recall (retrieve) and forget (delete), and includes concrete examples (ticker, address, preference).

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

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

Explicit guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names companion tools ('Pair with recall to retrieve later, forget to delete'), making alternative usage 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?

The description discloses significant behavioral traits beyond annotations: cascading internal lookups, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), source labeling of identifiers, and explicit listing of unresolved identifiers. This adds great value, especially since annotations already indicate read-only, idempotent, and non-destructive behavior.

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 fairly long but well-structured, front-loaded with purpose and examples. It could be slightly more concise (e.g., the detailed GLEIF/OpenFIGI explanation), but every sentence adds value. No waste.

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

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

Despite no output schema, the description thoroughly explains what will be returned (identifiers, source labels, unresolved list). It covers edge cases like graceful degradation and multiple input types. For a complex tool with cascading lookups, this is complete.

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

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

Schema coverage is 100%, but the description adds meaning: for 'company' type it accepts ticker, CIK, ISIN, or name; for 'drug' it accepts brand or generic name. It also explains the resolution logic for each type, which goes well beyond the schema's simple string descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with specific examples like 'ticker for...' and 'find the CIK for...'. It differentiates from siblings like entity_profile by emphasizing ID resolution rather than entity details.

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 FIRST whenever you have a name but need an ID.' This is a strong usage guideline. It does not explicitly state when not to use the tool or mention alternatives, but the context makes it clear that it's for name-to-ID conversion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that it 'probes each entity' using another tool, 'ranks by score', and returns a 'ranked list with score, confidence, signal density per entity'. This adds useful behavioral context about the internal process and output format.

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 well-structured sentences: function, method, use case, and return format. Every sentence earns its place with no redundancy or filler, making it easy to parse quickly.

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 appropriately explains the return format (ranked list with score, confidence, signal density) and the use case, making it self-contained. The annotations cover safety characteristics, and the schema covers parameters, so 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?

The schema already documents all 4 parameters with 100% coverage, so the baseline is 3. The description adds only marginal parameter context by mentioning 'your brand + N competitors' which aligns with the 'entities' schema description, but doesn't introduce new details about models, _apiKey, or context beyond what the schema provides.

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

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

The description clearly states the tool's function with a specific verb ('Compare AI visibility across multiple entities side-by-side') and explicitly distinguishes it from single-entity checks by referencing 'ai_visibility_check' and multi-entity ranking. The example query ('does Claude know about us as well as our competitors?') further anchors its purpose.

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

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

It identifies the appropriate context ('competitive AI-marketing audits') and implies when to use it (comparing multiple entities) versus single-entity tools like ai_visibility_check. While it doesn't explicitly name alternative tools or state when not to use it, the multi-entity framing provides clear 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?

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description goes further by disclosing partial failure degradation, the 5-30s latency for first-time bundlephobia measurements, and the sources_failed field. This operational context is not present in annotations and is essential for setting agent expectations.

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

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

The description is dense but remarkably efficient: it front-loads the core purpose, then usage triggers, return fields, ecosystem scope, and failure behavior. Every sentence serves a distinct purpose, and there is no redundancy or filler.

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

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

For a composite tool with no output schema, the description enumerates the exact fields in the summary block, per-advisory details, links, and alternative versions. It also covers failure modes and latency, making it complete enough for an agent to invoke the tool correctly and interpret the result.

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 100% coverage for both parameters with clear descriptions. The description adds an ecosystem constraint ('NPM ecosystem only') that clarifies the valid values for 'package', and it ties 'version' to the context of comparing alternatives. While not extensive, it does add 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 defines the tool as a composite check for 'should I add this npm package to my project', specifying that it combines deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake support). This verb-resource pairing is specific and distinguishes it from all sibling tools, none of which cover dependency scanning.

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: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides exclusion guidance, noting that the NPM ecosystem is the only supported one in v1 and that PyPI/Maven/Cargo/Go fall under deps.dev:version directly—thereby steering users to alternatives.

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

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

Annotations already cover read-only, idempotence, and non-destructive safety. The description adds meaningful behavior beyond that: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and has a 200K char cap with truncation flagging. This enriches the agent's understanding of mechanics 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 front-loaded with purpose and then efficiently covers usage, alternatives, technical details, and constraints. Every sentence contributes to the agent's decision-making—no filler or redundancy. It is appropriately sized for the tool's 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?

Despite lacking an output schema, the description fully covers what the tool returns (passages, offsets, similarity scores), the exact use case, the integration with a sibling, and the input length limit with truncation behavior. For a search tool with 3 parameters, this is complete and self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by connecting the limit parameter to 'top-N passages' and giving concrete examples for the query parameter (e.g., 'supply-chain risk', 'fiscal year 2024 revenue'). This contextualizes parameter usage beyond the schema's declarative descriptions, though not significantly beyond them.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from siblings by contrasting with ask_pipeworx_grounded, stating 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This uniquely positions search_within as a text-internal search 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?

The description explicitly states when to use it: 'Use when the record is too big to cram into the prompt.' It also names the complementary alternative (ask_pipeworx_grounded) and explains the workflow: fetch with the gateway, ground over relevant passages. This provides clear context and pairwise guidance with a sibling tool.

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

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

The description discloses significant behavioral traits beyond annotations: OAuth requirement, subscription persistence, return of new id, delivery channel behavior, phone verification, SMS cap, and webhook auto-disable after 10 failures. These add context without contradicting the annotations (readOnlyHint false, openWorldHint true, idempotentHint true, 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?

The description is dense and front-loaded with the purpose, then structured by subscription type and delivery channel. It is somewhat long but every sentence contributes useful information, so it earns a 4 rather than 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?

For a complex tool with three parameters, nested objects, multiple types, and delivery options, the description is remarkably complete. It covers auth prerequisites, return value, delivery channel specifics, usage limitations, and how to access the always-on feed. With no output schema, it adequately explains the core return value.

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

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

Schema coverage is 100% and the schema already includes detailed per-parameter descriptions. The description nonetheless adds practical semantics: concrete examples for sec_8k items, polymarket_edge topic, fred_series series_id, and delivery configuration constraints. It clarifies the significance of values and operational constraints beyond the schema.

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

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

The description clearly states a specific action ('Create a proactive monitoring subscription') targeting a resource ('live-data event stream'), and mentions the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear usage context: it requires a Pipeworx OAuth account, mentions that anonymous and BYO cannot persist subscriptions, and explains delivery channel options with preconditions (phone verification, 10/day cap). It doesn't explicitly name alternative tools, but it references pulling via recent_alerts, giving an implicit alternative for retrieval.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable context: it returns a structured list of example questions with tool+argument shapes, drawn from a live catalog, and explains the behavior with/without the topic argument. This goes beyond the annotations but doesn't disclose limits like freshness or pagination, which are not needed here.

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

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

The description is somewhat long but well-structured: it starts with natural language query examples, then explains the return value, usage, and when to use it. Each sentence contributes meaning, though the initial list of queries could be trimmed for brevity. It is front-loaded with the tool's purpose.

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

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

Without an output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes). It covers call variants, parameter behavior, and usage context. Given the tool's moderate complexity, the description is complete and self-contained.

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

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

The input schema already provides 100% coverage for the single optional 'topic' parameter with a description. The description adds further meaning by giving concrete example values ('finance', 'pharma', 'betting'), explaining that omitting it returns the full spread, and clarifying that the topic focuses the returned categories. This is above the baseline for complete schema coverage.

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

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

The description clearly states that this is the onboarding entry point for an agent, returning category-bucketed example questions with exact tool and argument shapes. It explicitly differentiates from sibling tools like ask_pipeworx and entity_profile by positioning itself as the 'first use' tool when the agent doesn't know what Pipeworx can do.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' It also explains optional topic filtering and when to omit it, making the decision context 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?

The description adds substantial behavioral detail: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This goes beyond the annotations (which already note non-destructive mutation) by specifying retention semantics and side effects.

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

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

Two sentences, front-loaded with the action, and every clause adds value: action, ownership, deactivation behavior, and an explicit pointer to recent_alerts. No fluff.

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

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

For a single-parameter tool with no output schema, the description covers the essential behavior, side effects, ownership constraint, and related tool. No significant 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?

The schema already fully describes the id parameter. The description adds the constraint that the id must belong to the caller's own subscription ('Ownership is enforced'), which is not in the schema.

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

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

"Cancel a subscription by id" is a specific verb+resource statement. The title "Unsubscribe from Alerts" reinforces the action, and it clearly differs from siblings like subscribe and list_subscriptions.

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

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

The description states 'Ownership is enforced — you can only cancel your own subscriptions,' giving a clear condition for use. It also mentions recent_alerts as an alternative for viewing historical events, but it does not explicitly point to list_subscriptions for discovery.

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 goes far beyond annotations by detailing the two pipelines, the exact verdicts returned, and the critical caveat that could_not_verify means the check did not happen and must not be treated as evidence. It also clarifies unsupported and error structure. Annotations already declare read-only/idempotent, so this adds significant behavioral context.

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

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

The description is lengthy but front-loads the purpose and trigger phrases. Each section earns its place: routing, return values, and failure semantics. It could be tightened slightly without losing clarity, but it remains structured and relevant.

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 covers return values, including the verdict list, citation, reasoning, and verification_error. It explains ambiguous verdicts (could_not_verify vs unsupported) and the exact behavior for different claim types, making it self-sufficient.

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

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

Both parameters are fully described in the input schema (100% coverage), so the description adds little beyond what's already there. It mentions tolerance behavior and claim examples but these are redundant with the schema descriptions. Baseline 3 applies.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with a specific verb (validate/verify) and resource (factual claims). It includes trigger phrases and examples, distinguishing it from general Q&A or research siblings. Replaces 4–6 sequential calls further clarifies its role.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear when-to-use condition. It also explains the two routing paths (company-financial vs other) and notes it replaces multiple sequential calls. However, it does not name specific alternative tools or state when not to use it, so it stops short of a 5.

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