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, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context by explaining that the tool routes to one of 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is information-dense and front-loaded with 'PREFER OVER WEB SEARCH,' which is good. However, it is quite long and has some redundancy, particularly the 'START HERE' sentence followed by 'If you need a single, fast, citation-backed answer, use ask_pipeworx,' and deep_research is mentioned twice in the routing guidance.

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

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

For a broad, routing-style question-answering tool with no output schema, the description is highly complete: it lists domains, trigger phrases, examples, citation behavior, and sibling alternatives. An agent has enough context to decide when to call this tool and what kind of question to pass.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the kinds of natural-language queries that work, listing trigger phrases like 'what is' and 'get the latest,' and giving concrete examples that clarify the expected content of the question parameter.

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 tool answers factual questions about real-world data by routing to thousands of verified source tools and returning citation-backed structured answers. It differentiates itself from siblings by explicitly naming deep_research, ask_pipeworx_grounded, validate_claim, and ai_visibility_check as alternatives.

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 to prefer this over web search, provides trigger phrases and concrete examples, and says 'START HERE for most questions.' It also gives conditional routing to alternatives: deep_research for multi-step reports, ask_pipeworx_grounded for verification, validate_claim for specific claims, and ai_visibility_check for page-index checks.

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, the description discloses rich behavioral context: current candidate routing status, that no candidate is active right now, that behavior matches ask_pipeworx exactly at present, that it is a live experimental edge, and that it 'falls back to nothing.' This is especially valuable because it prevents the agent from assuming degraded fallback behavior. The annotations readOnlyHint, idempotentHint, and destructiveHint=false are not contradicted.

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 essential beta/identity claim and then covers usage and fallback behavior clearly. It is slightly verbose with specific details like the 5,798 tool count and the exact retirement date, but these details are not harmful and each sentence earns its place. Minor redundancy in 'full working router' and 'experimental edge' keeps it from 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?

The description covers the current state, how to invoke it, and its fallback behavior, which is strong for an experimental router tool. There is no output schema, and while it references 'same response shape' as ask_pipeworx, it does not describe the response structure directly. It is complete enough given the sibling context, but slightly reliant on prior knowledge of ask_pipeworx for full invocation confidence.

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 all parameters and aliases documented in the input schema. The description adds only 'same arguments' and does not provide additional parameter-level meaning. This meets the baseline for full schema coverage, but does not elevate above it.

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 by identifying this as the beta version of ask_pipeworx and explicitly states it is an identical universal router with the same 5,798 tools, arguments, and response shape. It also distinguishes itself from the stable ask_pipeworx by calling itself 'the experimental edge' while still being 'a full working router.' This makes the tool's purpose and scope immediately clear.

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 direction: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It names the primary alternative, ask_pipeworx. However, it does not provide explicit when-not-to-use guidance or mention other related siblings like ask_pipeworx_grounded, so it falls just short of full exclusion 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?

Adds substantial behavioral context beyond the annotations: it discloses that the tool routes through internal tools, extracts from tool results only, returns a specific success envelope, and returns explicit refusal reasons when the data is insufficient. It also transparently notes the extra LLM call cost. No contradiction with readOnlyHint/idempotentHint/openWorldHint.

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 every sentence earns its place: it front-loads the core behavior, then details return shape, refusal behavior, use cases, and the cost tradeoff against the sibling. The density is justified by the high-stakes nature of the tool and the need to prevent misuse.

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 compensates by specifying the success return object and refusal object, including refusal reason values. It also provides the routing model, grounding guarantee, alternative tool, and cost context, so an agent has everything needed to invoke and interpret 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 coverage is 100% and all parameters are aliases for the same natural-language question, so the schema already fully documents the input. The description adds no additional parameter-level semantics beyond describing the tool as question-answering, which is already apparent. 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?

States a specific verb/resource combination and a distinctive behavior: hallucination-resistant, grounded answering that extracts only from tool results. It clearly differentiates itself from ask_pipeworx while explicitly naming the sibling it parallels. The description makes the tool's role immediately identifiable.

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?

Gives explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted upon and facts must not be invented. It also names the alternative ask_pipeworx and tells the agent to prefer it for casual lookups, which fully routes the decision between the two.

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 (readOnlyHint, openWorldHint, idempotentHint) cover the safety profile, and the description still adds substantial behavior: account/tier gating (thorough needs a paid plan), latency (15-60s, ~90s for thorough), return-packet shape, the gaps[] never-invents guarantee, contradictions[] behavior, fetchable citation_uri guarantee, parallel execution across 5,798 tools, and semantic excerpting. 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?

Though long, every sentence carries non-obvious operational information an agent needs — auth gating is front-loaded first, followed by purpose, routing, mechanics, guarantees, and latency. Given there is no output schema, this density is earned rather than padded; there is minimal redundancy with the schema.

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

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

For a complex tool with no output schema, the description is remarkably complete: it specifies the findings packet fields, failure semantics (explicit gaps[], never invented), citation fetchability, excerpting behavior, latency, auth requirements, and sibling routing. An agent has everything needed to call it correctly and set expectations.

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; both parameters are already documented well, especially depth's hop/contradiction mechanics. The description adds consequence-level meaning beyond the schema: per-depth latency expectations, the paid requirement for thorough in context, and the claim that 'multi-step questions resolve in one call', which helps an agent reason about depth selection.

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

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

The description states a precise verb-resource-scope: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. It explicitly differentiates from siblings — 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx' — so an agent can distinguish it from ask_pipeworx and other research siblings without ambiguity.

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

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

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data') with concrete example prompts, and explicit when-not-to with named alternatives ('If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx'). Also states an exclusion ('NOT open-web search'), leaving no inference required.

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?

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral details: parallel fan-out across sources, soft-fail behavior for USPTO, empty FDA sections being expected rather than errors, private-company handling via resolved:false, and the meaning of sources_used/sources_failed. 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 front-loaded with query examples and the key 'ALWAYS PREFER' guidance, and the semicolon-structured output breakdown keeps it skimmable. Some example phrasings and repeated input explanation could be trimmed, but the complexity of the tool and lack of an output schema justify most of the length.

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

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

This is a complex multi-source tool with no output schema, and the description compensates fully: it enumerates the return sections, explains edge cases like private companies and empty FDA data, and clarifies failure semantics. An agent has enough information to invoke the tool and interpret its results 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 covers both parameters at 100% with clear descriptions, including the accepted shapes for type and value. The description reinforces this with examples and notes that type values are interchangeable, but it adds little semantic meaning beyond what the schema already provides, so 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 states a specific purpose: 'full cross-source profile of a US public company in ONE parallel call,' supported by clear trigger examples like 'Tell me about X' and 'research Acme.' It differentiates itself from chaining single-pack SEC/XBRL/news lookups and positions itself as the holistic entity-profile tool rather than a resolver or comparator.

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 context: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and lists exact query phrasings. It does not explicitly state when to avoid this tool in favor of comparison or deep-research siblings, 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 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, and the description adds substantial behavioral detail beyond that: compatibility codes, temporal alignment null vs unknown semantics, the fee caveat, skipped-leg counters, and the fact that returned pairs are matched by keyword overlap, not a shared resolution source. This is unusually transparent about limitations.

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 with labeled sections: modes, response, safety fields, codes, skipped counters, and fee disclosure. It front-loads the core purpose and most sentences carry unique information. The density of codes and caveats makes it slightly heavier than strictly necessary, but it earns most of its length.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does: top_spreads_pp, compatibility_warning/codes, temporal_alignment, skipped_unclassified, low_confidence_pairs, fees_note, and skipped counters are all defined. Given the tool's complexity, the description is complete enough for an agent to call it and interpret results without external references.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it defines the topic parameter as pre-mapped shortcuts, explains that explicit ticker/slug override the mapped side, and notes that both modes share the same matcher. It does not exhaustively explain every parameter interaction, so 4 rather than 5.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by explicitly naming Kalshi as the second venue and by describing the shared-question matching logic.

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

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

The description explicitly lays out two modes — topic shortcuts vs explicit ticker/slug — and tells the agent both run the same matcher. It also warns that pre-mapped topics are often not tradeable ('pre-mapped ≠ tradeable'), providing clear usage expectations. It does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of full when/when-not routing.

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?

Beyond the readOnly/idempotent annotations, the description discloses crucial behaviors: ambiguous names return `figi_candidates` instead of asserting a single answer, unresolved identifiers are explicitly listed under `unresolved`, LEI/FIGI enrichment degrades gracefully when upstream sources fail, and every identifier is labelled with its source. These details materially shape agent expectations and are not visible from the annotations alone.

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

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

The description is dense and front-loaded with query examples, but the company type is expressed as one very long run-on sentence with multiple nested parentheticals, making it hard to scan. Some redundancy exists (e.g., 'other tools require as input' and 'replaces 2-3 manual lookups' say similar things). The detail is valuable, but better bulleted or segmented structure would improve readability.

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

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

Given there is no output schema, the description carries the burden of explaining return values, and it does so thoroughly: it names all returned identifiers, explains ambiguous-match behavior, explicitly covers unresolved results, describes fallback degradation, and even includes the citation format for drug lookups. An agent has enough context to call 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?

Although the schema already describes both parameters with 100% coverage, the description adds substantial semantic value: accepted formats for `value` (ticker, CIK, ISIN, name; brand/generic drug name), the warning to pass only the entity name, the explanation that trailing security-class words break FIGI matching, and the ISIN-to-LEI mapping behavior. This goes far beyond the schema's simple type/example 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 concrete natural-language queries and then states the precise purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes this tool as an identifier resolver rather than a profiling or validation tool, and it enumerates supported types (company, drug) and the identifiers returned.

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 'Use FIRST whenever you have a name but need an ID,' which is strong, actionable guidance. It also notes that the tool replaces 2-3 manual lookups and describes the internal cascading behavior. However, it does not explicitly name sibling tools as alternatives or state when not to use it, leaving some routing inference to the agent.

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

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

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.