W3c

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and nondestructive. The description adds value by detailing the return structure (per-model score, confidence, signals, raw_response + combined view) and cost implication for Anthropic (_apiKey means user pays directly). No contradictions with annotations.

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

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

Two sentences covering purpose, default behavior, optional key requirements, and return format. Front-loaded with the main action and output. Every sentence is informative with no 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?

Despite no output schema, the description fully explains what is returned (per-model score, confidence, signals, raw_response + combined view). With 4 well-documented parameters and clear use cases, an agent has all necessary information to decide and invoke correctly.

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

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

Schema coverage is 100%, but the description adds essential context: gives examples for 'entity' ('Pipeworx', 'OpenInvoice'), clarifies supported models and the optional apikey requirement for Anthropic, explains 'context' as disambiguation. This goes well beyond the schema's bare 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 uses specific verbs ('probe', 'score') and resource ('LLMs for what they know about a business/brand/product/topic'). It clearly distinguishes from sibling tools like 'entity_profile' (which likely provides a profile) and 'deep_research' (broader research). The mention of default model and optional Anthropic adds specificity.

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 cases are listed: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. While it doesn't explicitly state when not to use, the context implies it's for probing LLM knowledge. Could be improved by contrasting with sibling tools like 'entity_profile'.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context: it fills arguments automatically, routes across a large tool graph, returns stable pipeworx:// citation URIs, and handles news via live news packs. It doesn't discuss latency or failure modes, but with these annotations that gap is minor.

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

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

The description is relatively long but every part earns its place: preference declaration, domain coverage, internal mechanics, trigger phrases, examples, and routing alternatives. It is front-loaded with the most decisive instruction ('PREFER OVER WEB SEARCH') and is well organized for agent consumption.

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

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

For a complex router-style tool with no output schema, the description provides enough context for correct selection and invocation: input style, expected output (structured answer plus stable citation URIs), examples, and alternative routing for broader research. It doesn't explicitly mention ask_pipeworx_beta/grounded, but the core usage and behavior are fully specified.

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

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

The input schema covers 100% of parameters and already documents 'question' plus five aliases. The description contributes example queries and reinforces that input is natural language, but it doesn't add new parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description states exactly what the tool does: it routes a natural-language question to the right tool across 5,798 tools / 1,517 sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It strongly differentiates from web search and deep_research, but it does not explicitly distinguish from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', trigger phrases, and concrete examples. It also names an alternative for broad/multi-part queries ('use deep_research') and explains how breaking-news queries are already covered.

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 and idempotent annotations, it discloses that candidate routing improvements are enabled live, that no candidate is currently active, that this is a full working router with no fallback, and that results are used to decide merges. This gives the agent meaningful expectations about experimental variability.

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 beta identity and provides useful context in four sentences. It is slightly repetitive with phrases like 'identical', 'matches ask_pipeworx exactly', and 'use it exactly like ask_pipeworx', and the exact retirement date is unnecessary detail.

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, it explicitly states the response shape is the same as ask_pipeworx and fully explains the beta status, current behavior, and intended use. Annotations cover safety, so nothing essential for invoking this tool 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 six parameters as aliases for question with 100% coverage. The description adds no additional parameter semantics beyond saying the arguments are the same as ask_pipeworx, so the baseline score 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 this as the beta version of ask_pipeworx and describes it as a universal router with the same tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx sibling by its experimental routing status.

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 use this exactly like ask_pipeworx when the newest routing is wanted and explains how results are compared against the stable router. However, it does not explicitly state when not to use it or mention the grounded alternative, so the guidance is clear but not exhaustive.

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?

Goes far beyond the annotations by disclosing the exact success return shape, the full refusal_reason enum, the constraint that answers come only from the tool result, and the extra LLM call cost. This is rich behavioral context with no contradiction against the readOnly/idempotent annotations.

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

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

The description is front-loaded with the core purpose and each subsequent sentence adds decision-relevant detail: routing, return contract, refusal reasons, usage context, and cost tradeoff. It is long but dense, 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?

Because there is no output schema, the description correctly carries the full return contract and refusal semantics. It also covers the selection context, the relationship to ask_pipeworx, and cost behavior, making it complete for both invocation and tool choice.

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 even though the description adds no parameter-specific guidance. The description focuses on routing and output behavior rather than the question parameter, which is acceptable because the schema already documents all aliases and natural-language usage.

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

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

The description states a distinct mode: a hallucination-resistant answer mode that routes through Pipeworx and extracts answers only from fetched tool results. It clearly differentiates itself from the sibling ask_pipeworx by emphasizing grounded extraction, evidence, and refusal 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?

Explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also explains the cost tradeoff of one extra LLM call, giving an agent a clear decision rule.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral details: resolver contract with match confidence and alternatives, parent event extraction, news fallback retry logic, safety warnings for low-confidence and closed markets, wide spread tradeability, and cancellation rule parsing. 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 with headings (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the main purpose and usage. Every section adds value, though some could be condensed. Slight verbosity, but information density is high.

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

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

Given the tool's complexity (multiple data sources, edge cases, safety checks), no output schema, and rich annotations, the description covers everything an AI agent needs: input variations, output fields, error handling, performance considerations (include_raw), and domain-specific nuances like cancellation rules. Extremely thorough.

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

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

Schema coverage is 100%, but the description adds significant meaning: market can be slug, URL, or question; depth explained with examples (quick vs thorough); include_raw explained with size implications and use cases. The description enriches understanding beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It explains the input types (slug, URL, question) and what the tool does: resolve market, classify, fan out, return evidence packet + comparison. It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on research and data gathering.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides classifier examples and fan-out examples. While it does not explicitly state when not to use, the examples imply it is for research, not direct arbitrage or edge detection, which are covered by sibling tools. Clear context without exclusion.

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, and idempotentHint, so the bar is lower. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format including citation URIs. These go 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 thorough but slightly long. It is front-loaded with examples and clear structure. Every sentence serves a purpose, though some could be merged for brevity. Overall, it earns its length due to tool 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 no output schema, the description explains the return format (paired data + citation URIs), sorting, and data handling nuances. It covers both entity types completely, mentions max entities, and addresses edge cases like fiscal year handling. No gaps remain.

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 significant value beyond schema: it explains the meaning of 'type' (company vs drug) and 'values' (tickers/CIKs for company, drug names). It also gives examples for each type and clarifies max/min items (2-5), which is in schema but reinforced with context.

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

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

The description starts with multiple example queries that clearly indicate the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sibling tools like 'entity_profile' by stating it replaces 8-15 sequential lookups. The verb 'compare' is specific and the resource is defined as entities (companies/drugs).

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides trigger phrases like 'compare X and Y' and 'X vs Y', clarifying when to use. It does not give when-not-to-use, but the clear recommendation suffices.

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?

Even though annotations already mark this as read-only/idempotent/open-world, the description adds substantial behavioral detail: account/login requirements, latency expectations, parallel decomposition, gap arrays, contradictions, resolvable citations, and semantic excerpting. It also explicitly states it never invents missing data, which is critical trust information.

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

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

The description is long, but it packs in many essential operational details for a complex tool. It is front-loaded with the most critical constraint (account requirement) and the primary routing alternative. Some redundancy exists in the repeated ask_pipeworx guidance, but each sentence contributes meaningful decision-making or behavioral information.

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

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

With no output schema, the description fully carries the burden of explaining return values — and it does: findings packet with verbatim evidence, confidence, source, fetched_at, stable citation_uri, gaps[], contradictions[], and hop field. It also covers prerequisites, latency, and behavior on edge cases, making the tool fully comprehensible without needing to inspect additional metadata.

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 both parameters are well-described in the schema. The description goes further by enriching the depth parameter semantics (quick/standard/thorough behavior, paid tier requirement, gap recovery, lead chasing) and clarifying that the question parameter handles natural-language multi-part queries. This is strong added value beyond the schema.

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

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

The description clearly identifies the tool's specific purpose: grounded multi-source research across Pipeworx's structured data sources in one call. It uses concrete verbs (decomposes, routes, returns) and explicitly distinguishes itself from open-web search and sibling 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 explicit when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups and breaking/news topics, and use ask_pipeworx if not signed in. It also explains depth variants and when each is appropriate, leaving no ambiguity about alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral detail: returns top-N relevant tools with full schemas and curated examples, ready to call directly.

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

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

Single, well-structured sentence leads with purpose, then usage guidance, then details. Every clause earns its place 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?

No output schema, but description fully explains what is returned (tool names, descriptions, full schemas with examples) and lists covered domains, making it complete for its purpose.

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

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

Schema description coverage is 100% with rich parameter descriptions. The description adds value by listing example queries and noting alias flexibility, though baseline is 3.

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

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

Clearly states verb 'find' and resource 'tools', with specific examples of tasks (SEC filings, FDA drugs, etc.) that distinguish it from sibling tools which are specific actions.

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

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

Explicitly advises to call 'FIRST' when exploring many tools and wanting to see the option set, providing clear context for use but lacking explicit when-not conditions.

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

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

Annotations already mark it read-only and idempotent, so the bar is lower — yet the description still adds substantial behavior: soft-fail semantics ('soft-fails until reactivated'), the Purple Book caveat that missing fda_products is expected for non-biologic companies, 'an empty section is a real no data, not a bug,' name resolution via SEC EDGAR, private-company resolved:false handling with a notes line, and the type/value interchangeability. This is exactly the edge-case context an agent needs.

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

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

Long but appropriately so for an 8-source fan-out with no output schema. It is front-loaded with trigger phrases and the core purpose before details. Minor redundancy: value shapes and type interchangeability restate the schema, and the seven example phrases could be trimmed to three without losing signal — but nothing is extraneous relative to 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?

With no output schema, the description carries the full burden of documenting return semantics — and it does thoroughly: cik/company_name/resolved_from/resolved_to, recent_filings with pipeworx URIs, fundamentals from the LATEST 10-K, per-source section behavior, and sources_used/sources_failed diagnostics. Failure modes, valid-empty results, and input validation are all covered. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema: 'type accepts company or ticker interchangeably — both take the same value shapes,' plus the behavioral consequence of passing a name (SEC resolution, resolved_from/resolved_to) and the private-company fallback. This enriches parameter understanding without repeating schema text verbatim.

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?

Opens with seven concrete trigger phrases, then states the core function precisely: 'full cross-source profile of a US public company in ONE parallel call.' The verb+resource+scope is unambiguous, and the enumerated fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA, DOL, news, and GLEIF clearly distinguishes it from single-pack lookup tools.

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

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

Provides explicit routing guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' naming the alternative approach and the triggering condition. However, it never acknowledges research/compare siblings in the tool list (deep_research, compare_entities, resolve_entity), leaving some routing decisions to inference.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the action 'delete' but doesn't disclose additional behavioral traits like whether deletion is immediate or reversible.

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

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

Two sentences with zero waste. Purpose, usage guidelines, and sibling pairing are all front-loaded.

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

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

For a simple delete tool with one parameter and comprehensive annotations, the description adequately covers purpose, usage, and relationships to siblings. No missing information.

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 parameter 'key' is described in schema as 'Memory key to delete'. The description says 'by key' which adds no new meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' by mentioning 'previously stored'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with alternatives 'remember' and 'recall'.

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

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

Annotations already signal safe, read-only, idempotent behavior. The description adds value by detailing the process: fetches page, extracts title/description/key links, emits standard format. 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 concise and front-loaded: starts with the main purpose, then explains the process, then lists use cases. Each sentence adds value, though it could be slightly tighter without losing clarity.

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

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

Given the tool's simplicity (2 params, no output schema, good annotations), the description is complete. It explains input, process, output format, and use cases. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal new information about parameters beyond what's in the schema (e.g., default and max for max_links are already in the schema). No significant extra meaning.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifies the output format, and lists specific use cases. It distinguishes itself from sibling tools, none of which serve the same 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?

The description explicitly provides three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it doesn't state when not to use or mention alternatives, the guidance is clear and practical.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by detailing the return fields and the option to include inactive subscriptions, but does not disclose any additional behavioral traits beyond what annotations imply.

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

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

Two sentences: first states purpose and key return fields, second gives usage guidance. No redundant or extraneous content; every sentence serves a purpose.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides sufficient context: what it returns, when to use it, and the effect of the parameter. No obvious gaps.

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

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

Schema coverage is 100% and the parameter 'include_inactive' is described in the schema. The description mentions 'active' subscriptions, which relates to the default behavior, but adds minimal extra meaning beyond the schema.

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

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

Description explicitly states what the tool does (list subscriptions), specifies the returned fields (id, type, params, etc.), and distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

Provides clear guidance on when to use the tool ('review what you're monitoring before adding more or to find an id to cancel'), but does not explicitly state when not to use it or mention alternatives.

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

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

Annotations are all false/neutral, so the description carries full burden. It discloses rate limiting (5/day), cost (free, no quota), the claim_token workflow for tracking resolution, and processing cadence (daily digests, roadmap signal). 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?

Lengthy but purposeful; each sentence adds distinct operational detail (scope, exclusions, token semantics, limits). Front-loaded with a clear purpose statement. Slightly verbose but well-structured and information-dense.

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 feedback tool with 4 parameters and no output schema, the description covers who receives feedback, what to report, exclusion criteria, token return/usage, rate limits, and team behavior, leaving no material gaps.

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

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

Schema already documents each parameter at 100% coverage; description adds crucial semantics for claim_token as a follow-up retrieval mechanism and advises on message content (describe in terms of Pipeworx tools/packs, don't paste end-user prompt), going beyond schema.

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

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

The description opens with a specific imperative—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and enumerates feedback categories (bug, feature/data_gap, praise). This clearly distinguishes it from sibling tools that perform research or visibility checks rather than collect feedback.

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

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

Explicitly states when to use (tool returns wrong/stale data, missing tool, praise) and when not to (tools from other MCP servers), even directing users to file those elsewhere. Includes a disambiguation cue ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare safe read-only. Description adds data source (CF analytics-engine), no PII, caching behavior, and aggregation method. No contradictions.

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

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

Three concise sentences plus bullet points, front-loaded with main purpose, no wasted words.

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

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

Given no output schema, description sufficiently explains return (top tools, packs, call volume). Caching and source mentioned. Complete for a simple trending 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?

Only parameter 'window' fully described with enum and semantic guidance. Schema coverage 100%, description adds meaning beyond enum values.

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

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

Clear verb 'returns', specific resources (top tools, packs, call volume), and differentiated from siblings like discover_tools. Explicit use cases.

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

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

Three specific use cases listed, plus guidance on window selection. No alternatives mentioned but 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 goes far beyond annotations, detailing behavioral traits such as semantic anchor with Jaccard similarity >=0.30, partition filter dropping placeholder slugs, fill check with CLOB depth, and response fields including opportunities, partition_check, and fill check. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose and modes, but it is quite lengthy and contains technical jargon (monotonicity, partition_check). While detailed, it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (multiple modes, fill check, response structure) and no output schema, the description is comprehensive. It explains the response format, fill check logic, and references polymarket_fill_risk for custom sizing, leaving no critical gaps.

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

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

Although schema descriptions cover both parameters, the tool description adds substantial semantic detail: for event, it explains the partition check and example slugs; for topic, it explains cross-event scanning, seed questions, and semantic anchor. This significantly enriches the meaning beyond the schema.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', providing a specific verb ('find'), resource ('arbitrage opportunities on Polymarket'), and method ('monotonicity violations + partition-sum checks'). This distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly explains when to use no arguments ('trending_scan'), event argument ('recommended for a specific market'), and topic argument ('for cross-event scanning'). It also provides an alternative: 'For custom sizing use polymarket_fill_risk', guiding the agent to the appropriate tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: explains the three model families with their underlying data sources (FRED log-returns, GDELT), edge calculation details (slippage subtraction, Kelly sizing caps), caching behavior (KV-level, 1h, keyed on knobs), and diagnostic output structure. No contradictions with annotations.

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

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

The description is well-structured with clear labeled segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and a bullet-like response outline. However, it is quite verbose with detailed model formulas and internal mechanics that may be excessive for general tool selection. A slightly more concise version could improve readability without losing essential information.

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

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

Given 9 parameters, no output schema, and numerous siblings, the description thoroughly covers the tool's behavior, edge cases (e.g., Fed bets unreliable), diagnostic output for empty segments, and caching policy. It provides enough detail for an agent to understand when and how to invoke the tool correctly, including tradeable-edge knob usage.

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

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

Schema coverage is 100% with each of the 9 parameters having a description. The tool description adds significant meaning beyond the schema: explains how parameters like min_liquidity, max_spread_pp act as 'Tradeable-edge filters', details the effect of min_partition_leg_kelly on per-leg Kelly, and clarifies default values and use cases (e.g., slippage_pp context on Polymarket fees).

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the output segments (model_driven, structural_arbitrage, concentrated_longshot) and explicitly targets the use case 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx-driven edge detection.

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

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

The description provides explicit guidance on when to use the tool ('what should I bet on today') and details the tradeable-edge knobs (min_liquidity, max_spread_pp, etc.). It explains how to filter results and interpret diagnostics. However, it doesn't explicitly state when not to use it or compare directly with alternatives, though the context implies separate tools for different tasks.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds details: reads snapshots, returns tracked, expired, snapshot_dates, and explains data derivation (decay from daily closes). No contradiction.

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

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

Well-structured: purpose, response fields (tracked, expired, snapshot_dates), then limitations. Slightly verbose but every sentence is informative.

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

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

No output schema, but description thoroughly explains the response structure (tracked[] with time-series, expired[], snapshot_dates[]) and limitations. Covers inputs, outputs, and context comprehensively.

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

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

Both parameters have schema descriptions (100% coverage). Description adds context like default and max for days, enumeration for window. Schema already covers well, so description adds marginal value.

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

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

The description states the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It clearly distinguishes from sibling polymarket_edges by focusing on time-series 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?

Implied usage: compare fresh vs old edges. Limitations noted (60-day TTL, daily closes). No explicit when-not-to-use or alternatives, but context is sufficient.

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

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

Annotations already show readOnly, but description adds behavioral details: walks order book ladder, returns specific fields (slippage, fill details), explains basket behavior, and warns about forced directional risk. No contradiction.

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

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

Well-structured with clear sections for modes, but verbose. Could be more concise for an AI agent. Front-loaded with 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?

Thoroughly covers both modes, return fields, edge cases (thin_legs, forced_directional_risk), and usage context. No output schema, but enumerates what is returned.

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 good descriptions. Description adds context beyond schema: clarifies size_usd interpretation for buys vs sells and basket mode. Slightly above 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verb-resource pairing. It distinguishes between single-market and basket modes, differentiating it from siblings like polymarket_arbitrage.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Describes when to use and warnings about partial fills converting arbs into directional positions.

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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: it explains that the tool may return compatibility_warning even when pairs exist, describes specific compatibility codes, clarifies that temporal_alignment_unknown is not the same as aligned, notes that Kalshi fees are not modeled, and describes why skipped counters exist. It also gives a realistic expectation that real cross-venue spreads are rare. No contradictions with annotations.

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

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

The description is long but highly structured: it starts with the core purpose, then modes, then response details, then safety fields, then fees and skip counters, ending with a caution about pre-mapped topics. Each section earns its place, but it is dense and may be overwhelming for a quick scan. It is appropriately front-loaded with the key purpose.

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

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

Given the tool's complexity (two modes, multiple compatibility codes, nested flags, fees, skip counters), the description covers all aspects an agent needs: it explains the response structure (top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, skipped counters), how to interpret ambiguous fields, and edge cases like unclassified legs. No output schema, so the description must carry this burden, and it does thoroughly.

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

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

Schema covers all parameters with descriptions. The description adds meaning by explaining how topic maps to events, that explicit tickers override the topic-mapped side, and that both modes use the same matcher. It also clarifies that no parameters are required (0 required), which is useful. This goes beyond the schema's basic descriptions.

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

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

The description begins with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details two modes (topic shortcuts and explicit tickers) and what responses include. This clearly differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue spreads.

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 explains when to use topic mode versus explicit pairing, and warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility_warning today. It implies when not to rely on it (shortcut topics may not be aligned), but doesn't explicitly mention alternatives or conditions to avoid the tool entirely.

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?

Given annotations already indicate readOnly and idempotent, description adds valuable scope information (scoped to identifier) and listing behavior (omit key to list). No contradictions.

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

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

Two sentences, no wasted words. First sentence defines core behavior, second adds usage and scope. Efficient and front-loaded.

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

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

For a simple get/list tool with good annotations and schema, description fully covers usage, scope, and pairing with siblings. Output behavior (returning value or list) is implied by the description.

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

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

Schema coverage is 100%, but description adds critical context: omitting key lists all keys. This clarifies optionality and dual behavior beyond the schema description.

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

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

Description uses specific verb (retrieve/list) and resource (saved values/keys). Clearly distinguishes from sibling tools remember (save) and forget (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?

Provides explicit context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes'. Mentions scope and pairing with remember/forget, though no explicit when-not-to-use.

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

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

Annotations provide strong behavioral hints (readOnly, idempotent, openWorld). The description adds important context: the mark_read parameter causes side effects by flagging events as read, and that polling is acceptable. 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 three sentences long, front-loaded with the core purpose, and each sentence adds a distinct piece of information (what it returns, how to filter, mark_read behavior, alternative access). No extraneous content.

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

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

For a tool with 5 optional parameters, no required fields, and no output schema, the description covers the return format, filtering options, mark_read behavior, and alternative access. It lacks an explicit mention of ordering (e.g., most recent first), which would enhance completeness.

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

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

Schema coverage is 100% with individual parameter descriptions. The description adds value by providing examples (e.g., type 'sec_8k') and clarifying the effect of mark_read and since filters, which goes 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 clearly states it pulls fired events from a subscription feed and returns recent alerts with source, citation URI, and payload. This verb+resource specification is distinct from sibling tools like list_subscriptions or subscribe, which serve different purposes.

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 notes that polling works fine and points to an alternative API endpoint for scripts/dashboards, giving context on when to use this tool vs an HTTP request. However, it does not explicitly exclude cases or compare with other tools like search_within.

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 it as read-only and idempotent. The description adds valuable behavioral details: fan-out logic, fallback from GDELT to GNews, USPTO soft-fail due to sunset, and return structure.

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

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

The description is thorough but well-structured with front-loaded examples. Every sentence provides useful information, though it could be slightly trimmed without losing value.

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

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

Given the tool's complexity (multiple sources, fallbacks, parameter formats) and no output schema, the description is comprehensive: it explains all key behaviors, inputs, and outputs (grouped changes, total count, URIs).

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: explains 'since' format with examples, clarifies 'value' accepts ticker or CIK, and notes 'type' only supports 'company'.

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 provides a change feed for a company, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from sibling tool 'entity_profile' by specifying what each tool covers.

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

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

The description explicitly tells when to use this tool (for recent changes) and when to use the alternative 'entity_profile' (for static profile). It also gives example queries to guide usage.

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

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

Annotations already provide idempotentHint, readOnlyHint, destructiveHint. Description adds persistence details (authenticated vs anonymous 24h) and scoping by identifier. No contradiction with annotations.

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

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

Description is a single paragraph of four sentences, each adding value. Front-loaded with main purpose and usage. Could be slightly more structured but very efficient.

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

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

For a simple two-parameter write tool with no output schema, description covers persistence, scoping, and sibling tool pairing. No missing essential information.

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

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

Schema coverage is 100% with descriptions. Description adds example values (e.g., 'subject_property', 'target_ticker'), providing extra context beyond schema. Baseline 3 raised to 4 due to added examples.

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?

Title and description clearly state the tool stores data for later reuse. Uses specific verb 'save data' and resource 'key-value pair scoped by your identifier'. Distinguishes from siblings recall and forget by mentioning pairing.

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

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

Explicitly says when to use: when discovering something worth carrying forward, with examples. Does not explicitly state when not to use, but pairs with recall/forget, implying alternatives. Clear context for usage.

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

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

With annotations already carrying readOnlyHint and idempotentHint, the description still adds substantial behavioral detail: identifier source labeling, explicit `unresolved` reporting, `figi_candidates` on ambiguity, graceful degradation when GLEIF/OpenFIGI are unavailable, and ISIN-to-LEI mapping. No description detail contradicts 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 dense and front-loaded with user-style queries, and nearly every clause adds useful information. However, the company type explanation is one extremely long parenthetical with multiple semicolons and em-dashes, making it harder to scan than it needs to be. A little restructuring would make it concise without losing information.

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

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

With no output schema, the description must communicate what values come back, and it does: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, `figi_candidates`, and `unresolved`. It also covers input variants, ambiguity, fallback behavior, and external source dependencies, making it complete for an agent deciding whether and how to call 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?

Although schema coverage is 100%, the description adds real meaning beyond the schema: `value` also accepts ISIN, non-equity instruments resolve even without tickers, drug lookups return RxCUI plus ingredient and brand, and ambiguous names return `figi_candidates`. It also reinforces the schema warning about passing only the issuer name, not the full noun phrase.

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

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

The description names a concrete verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from likely siblings by enumerating supported entity types and explicitly positioning itself as the first move when 'you have a name but need an ID.'

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

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

It gives an explicit usage condition: 'Use FIRST whenever you have a name but need an ID.' It also explains that one call 'replaces 2-3 manual lookups.' It does not name alternatives or explicitly state when not to use this tool versus sibling research/profile tools, so it falls just 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 declare safe, read-only, idempotent behavior. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns score/confidence/signal density. This provides useful behavioral context beyond annotations.

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

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

The description is concise (4 sentences) with front-loaded main function. It provides all necessary information without unnecessary fluff.

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

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

Given no output schema, the description adequately describes return format ('ranked list with score, confidence, signal density per entity'). It could mention the allowed entity count range (2-8) explicitly, but schema covers this.

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 insight that the first entity is treated as the 'subject' and that context disambiguates names, but does not significantly expand on schema definitions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, differentiating from sibling ai_visibility_check which likely handles single entities. It uses specific verbs ('compare', 'ranks') and specifies the resource ('AI visibility across multiple entities').

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

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

The description explains when to use it ('competitive AI-marketing audits') and provides a concrete example question. However, it does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entity 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?

Describes fan-out across multiple APIs, graceful partial degradation with timeout details (bundlephobia first measurement 5-30s), and return structure. Adds significant context beyond annotations.

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

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

Packed with information but a bit lengthy. However, every sentence is purposeful and well-structured, front-loading purpose and usage.

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

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

Despite no output schema, description covers return format, error handling, and limitations thoroughly. Agent can confidently invoke the tool and interpret results.

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

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

Schema coverage is 100% so baseline is 3. Description adds useful context (scoped packages accepted, version defaults to latest) but largely aligns with schema. Slight value add beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, etc. It distinguishes from sibling tools by specifying its scope (npm ecosystem) and data sources.

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

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

Explicitly provides when to use: when agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies ecosystem constraint (NPM only v1) and notes that other ecosystems fall under different tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), character limit (200K chars with truncation flag), and support for verifying verbatim quotes via offsets.

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?

Every sentence earns its place. The description is front-loaded with the core purpose, then provides usage context, pairing advice, and technical details. No redundancy or fluff, and it remains under three sentences of substantive content.

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

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

Despite having no output schema, the description fully explains the return structure: top-N passages with character offsets and similarity scores. It also covers the 200K char limit and truncation behavior. For a search tool with three parameters, this is complete and leaves no gaps.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds further context: 'natural-language query' with examples, 'max ~200K chars' for text, and default/max for limit (1-20, default 5). This enriches the schema 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 clearly states the tool performs 'semantic search INSIDE a fetched record' and returns top-N passages with character offsets and similarity scores. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded as a complementary tool, and the title 'Search Within a Source' reinforces the specific action.

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 concrete usage guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context with passage offsets. It also pairs the tool with ask_pipeworx_grounded, but does not explicitly list when not to use it or alternative 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?

Discloses behavioral traits beyond annotations: requires OAuth, no persistence for anonymous/BYO, returns subscription id, SMS 10/day cap, webhook auto-disabled after 10 failures, feed always on. No contradiction with annotations (readOnlyHint=false, etc.).

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?

Effective front-loading of purpose, but the dense single paragraph with detailed examples could be more scannable. Still, each sentence adds value without waste.

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

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

Comprehensively covers use cases, requirements, supported types, delivery options, limits, and return value. No output schema, but the description implies the response includes subscription id. Addresses complexity well.

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

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

Schema coverage is 100%; description adds significant meaning: for 'type', explains each enum value with examples; for 'params', gives type-specific structures; for 'delivery', details sub-properties with constraints and examples, exceeding 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 'Create a proactive monitoring subscription to a live-data event stream', clearly identifying the action (create) and resource (subscription to event stream). It differentiates 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?

Provides context on when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). Lists supported alert types and delivery channels, but does not explicitly exclude scenarios or compare directly to sibling tools like polymarket_arbitrage.

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

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

Annotations comprehensively cover behavioral traits (readOnlyHint, openWorldHint, etc.). The description adds value by explaining the output structure (category-bucketed questions with tool+argument shapes) and confirms no side effects. 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 somewhat lengthy but well-organized, front-loading the core purpose with multiple example queries. Every sentence serves a purpose, though minor redundancy exists in the list of categories.

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 explains what the tool returns (category-bucketed examples with tool+argument shapes). Given the tool's simplicity and the rich annotations, this is complete and sufficient for agent use.

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

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

Schema coverage is 100%, but the description adds contextual semantics: clarifies the topic parameter's allowed values and behavior (omit for full spread, specify for focus). This goes beyond the schema's generic description.

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

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

The description clearly states the tool returns category-bucketed example questions to help users understand Pipeworx's capabilities, using specific verbs like 'returns' and 'shows examples'. It distinguishes itself from siblings as the onboarding entry point, which is unique among the listed tools.

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

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

Explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear context for when to use this tool vs alternatives, and includes guidance on the optional topic parameter.

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

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

Annotations indicate non-readOnly, non-destructive, idempotent. The description adds valuable context: ownership enforcement, deactivation (not deletion), and that historical events remain accessible via recent_alerts. No contradiction with annotations.

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

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

Two sentences, front-loaded with the main action, and each sentence adds essential information without redundancy or fluff.

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

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

Given low complexity (1 param, no output schema), the description covers purpose, ownership, behavior, and post-condition. It does not mention error cases (e.g., id not found) or return value, which could be helpful but are not critical for this simple operation.

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?

Only one parameter 'id' with schema coverage 100% and a clear schema description ('Subscription id (uuid) returned by subscribe.'). The description adds 'by id' which matches the schema, providing no additional meaning beyond 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 clearly states the verb 'Cancel' and resource 'subscription'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying behavior (deactivation vs deletion) and ownership enforcement.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains that the row is deactivated, not deleted, so historical events remain available. It does not list alternative tools or explicit when-not cases, but the context is clear enough.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses detailed behavioral semantics: the full verdict vocabulary, that evidence is returned with pipeworx:// citations, and the crucial distinction between could_not_verify (a failed check, not evidence) and unsupported (no source found). It also explains the internal pipeline stages, giving the agent an accurate mental model of what happens.

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

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

The description is long but densely informative, front-loading usage examples and then layering routing, verdicts, and error semantics. Every section adds value, though a few phrases like 'routed to the right live source, answered with verbatim evidence, then judged' could be tightened 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 complexity and lack of an output schema, the description is remarkably complete: it specifies all possible verdicts, explains what evidence and reasoning are returned, clarifies error handling with verification_error{stage,detail}, and even notes the tool replaces multiple sequential calls. No critical behavioral aspect is left unexplained.

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 both parameters are well-documented in the schema, so the description does not need to add parameter syntax. The description adds context about 'exact percent-delta math' and the tolerance default, but this is marginal beyond the schema's existing description of tolerance_pct overriding claim wording.

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 examples and clearly defines the tool as claim verification against authoritative sources. It distinguishes itself from siblings by explaining the two routing paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for everything else) and by noting it replaces 4–6 sequential calls.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear usage guidance. It also provides routing details for company-financial vs. other factual claims, but does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detail on return fields (shortname, title, status, organization, URL) which is useful and 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?

Two sentences plus an example call, zero wasted words, front-loaded with purpose. Highly efficient.

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

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

Given small parameter count (2), no output schema needed, the description fully covers what the tool does and returns. Examples help clarify usage. Complete for a search 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 both parameters described. The description adds examples but does not significantly extend schema meaning, so 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 verb (Find) and resource (W3C/web-standards specifications), provides specific examples of queries and return fields, and distinguishes from sibling tool 'w3c_spec' by focusing on search.

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 use cases like 'what W3C spec defines X' but does not explicitly exclude scenarios or mention alternatives like w3c_spec for retrieving a single spec.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by listing the specific return fields (title, status, organization, etc.) and input flexibility, which provides useful behavioral context beyond annotations.

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

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

The description is three sentences long, covering purpose, return data, and input flexibility. It is concise without being overly terse, though structuring with bullet points could improve scanability. No unnecessary information.

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

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

Given the simple parameter (one optional string) and no output schema, the description adequately covers input formats, example usage, and return fields. The annotations compensate for missing output schema by declaring idempotency and read-only nature, making the description complete for this 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?

The schema covers 100% of parameters with a description, but the tool's description enriches this by explicitly stating that it accepts shortname, name, or title, and provides concrete examples. This goes beyond the schema's brief description.

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

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

The description clearly identifies the tool's purpose: retrieving details for a single web-standards spec using a shortname or title fragment. It specifies the verb 'returns' and the resource, and distinguishes from sibling w3c_search by focusing on single spec retrieval.

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 usage context by mentioning acceptable inputs (shortname, name, title) and gives an example call. However, it lacks explicit guidance on when to use this tool versus the sibling w3c_search tool, which is a minor gap.

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