wikipedia

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

Annotations already declare this as a safe read-only, idempotent operation. The description adds valuable context: the default free Workers AI model, the BYO Anthropic key with direct cost to the user, and the per-model response structure ({score, confidence, signals, raw_response}), which goes beyond annotation metadata.

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

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

Three sentences with the main action up front, followed by key details (default model, cost, return format) and use cases. No filler or redundant phrasing.

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 explicitly states the return shape and covers key usage scenarios. For a simple read-only tool with fully documented params and annotations, this is adequately complete; it could mention the exact models supported or signal semantics, but that's not critical.

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

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

All four parameters are already fully described in the schema (100% coverage), so the baseline is 3. The description adds some cross-parameter context (e.g., '_apiKey' is only needed if 'anthropic' is in the models array) and clarifies cost implications, but it doesn't provide syntax or format details 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 uses a specific verb ('Probe') and clearly states the tool's function: querying LLMs about an entity and producing a visibility score (0-100) per model. It distinguishes itself from sibling read/search tools by focusing on AI brand awareness scoring rather than general Q&A or research.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which tells the agent when to choose this tool. However, it doesn't name alternative tools or state when not to use it, only the intended scenarios.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: the routing mechanism, the number of tools/sources, the return format with stable pipeworx:// citation URIs, and performance characteristics ('one fast call', 'works on every tier'). 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?

Though lengthy, the description is densely packed with actionable information. It uses bolded directives for emphasis, provides examples in a structured list, and ends with explicit alternative tool comparisons. No wasted words—every sentence contributes to either purpose, usage, or behavioral transparency.

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

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

The description is remarkably complete for a tool with one parameter and no output schema. It covers the tool's role, scope, example queries, alternative tools for specific needs, and the return format (structured answer with citations). An agent can confidently invoke this tool and understand what to expect without additional documentation.

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

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

The schema has 100% coverage with clear alias descriptions for the single natural-language question parameter. The description adds value by giving concrete examples of valid questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifying that it accepts natural language. It doesn't explain parameter syntax beyond the schema (which already does), but the examples enhance practical understanding.

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

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

The description clearly identifies the tool as a question-routing engine: it routes questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It goes beyond the title 'Ask Pipeworx' and explicitly distinguishes itself from web search and sibling tools, making its purpose unmistakable.

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

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

The description gives explicit directives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also covers breaking news routing. This provides complete when-to-use vs when-not-to-use guidance.

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

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

Annotations already declare safe read-only/idempotent behavior. The description adds valuable context about the beta nature: live candidate switching, the current status (no active candidate, retired 2026-07-26), and that it falls back to nothing (still a full router). This goes beyond the annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core identity ('Beta version of ask_pipeworx...'), and every sentence adds key information—tool count, identical interface, experimental candidate behavior, current inactive state, and usage guidance. No fluff or repetition.

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

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

For a router with no output schema, the description adequately orients the agent by referencing the exact same response shape as ask_pipeworx, connecting to a known sibling. It also states it is a full working router, mitigating a common misunderstanding about beta tools. It does not list possible return fields, but that is covered by the sibling reference.

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

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

The input schema has 100% coverage, with all six parameters documented as aliases for 'question'. The description adds no parameter-specific detail, which is acceptable given the schema's thoroughness. Baseline 3 applies.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape, but with candidate routing improvements. It explicitly distinguishes itself from the stable ask_pipeworx sibling by being the experimental edge.

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 instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router to decide merges. This gives clear when-to-use guidance and implicitly names the alternative (stable ask_pipeworx).

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?

Extensive behavioral context is added beyond annotations: it costs an extra LLM call, returns a structured response with refusal reasons, and only extracts from tool results. The description details the success and refusal output shapes, which is valuable since no output schema exists.

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

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

The description is dense but well-structured, covering purpose, behavior, response format, usage guidance, and tradeoffs in about five sentences. No word is wasted; each sentence delivers distinct, useful information.

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

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

Given the tool's complexity (routing across thousands of sources) and lack of an output schema, the description provides comprehensive context: return fields, evidence quotes, confidence scoring, and explicit refusal reasons for each failure mode. It also explains the extra cost, making the complete picture actionable for an agent.

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

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

Schema coverage is 100% (all parameters are aliases of the single 'question' parameter), so the baseline is 3. The description does not add further parameter-level semantics, but it does reference routing and argument filling in the pipeline, which slightly contextualizes the parameter.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains its unique extraction behavior. It distinguishes itself from sibling ask_pipeworx by noting 'same routing' but adding evidence-grounded extraction and explicit refusal reasons.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This tells the agent exactly when to choose this tool versus its sibling, including a cost tradeoff.

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 with readOnlyHint/idempotentHint annotations, the description goes far beyond them by disclosing critical behaviors: the resolver contract with confidence levels, low-confidence short-circuiting, closed-market handling, wide-spread illiquidity flags, parent-event extraction, and resolution-rule risk (cancellation/void settlement). This is precisely the contextual richness that annotations alone cannot convey.

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

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

The description is lengthy but extremely well-structured with clear section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and a front-loaded purpose statement. Each section earns its place given the tool's complexity, though certain details could be condensed 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?

In the absence of an output schema, the description comprehensively documents all return shapes: result.market, result.analysis, result.evidence, statuses, parent_event, news fallback fields, and resolution-risk warnings. It also covers safety mechanisms and blocking behaviors, leaving few ambiguities for an AI agent to invoke the tool correctly 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?

The input schema provides 100% coverage for all three parameters (market, depth, include_raw), including their descriptions and defaults. The description reinforces the `market` parameter's accepted formats (slug/URL/text) but adds no new semantics beyond the schema. Since the schema does the heavy lifting, a 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 explicitly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling Polymarket tools (e.g., polymarket_edges, polymarket_arbitrage) by focusing on evidence gathering and market-vs-model comparison. The verb 'Research' and specific resource (Polymarket bet) make the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples for different bet categories, showing when the tool is applicable. However, it does not explicitly compare against sibling tools or state when NOT to use it, leaving a minor gap in exclusion guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond that: source data (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. There is 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 dense but front-loaded with trigger phrases and a clear directive. Every sentence contributes unique information—usage triggers, data sources, sorting behavior, and efficiency gains—without redundancy or filler. It is structured to be scannable and immediately actionable.

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 2-parameter schema, strong annotations, and no output schema, the description fully covers what the tool returns (paired data, citation URIs), how results are ordered, and what each type does. It also names the alternative approach it replaces, making its role in the toolset clear. No significant 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?

Although schema coverage is 100%, the description enriches the parameters substantially: it explains what 'type' maps to in terms of data sources, gives concrete examples for 'values' (tickers vs drug names), and clarifies output behavior (sorted by primary metric). This goes well beyond the schema's terse property descriptions.

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

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

The description uses specific verbs ('compare', 'rank', 'side-by-side') with a clear resource ('companies or drugs'), and explicitly differentiates itself from sequential single-entity lookups. It also enumerates concrete query phrasings that trigger the tool's use, making its purpose unmistakable.

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

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

The description provides explicit usage criteria: trigger phrases like 'X vs Y', 'which is bigger', 'rank these companies', and a strong directive to always prefer this over sequential single-pack lookups when comparing entities. It also gives per-type data sources, clarifying when company vs drug comparison is appropriate.

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 account tier limitations, latency expectations (15-60s, up to ~90s), the gap[] behavior (never invents answers), contradictions[] for standard/thorough, semantic excerpting, and the guarantee that citations are resolvable. This rich context exceeds what annotations alone provide.

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

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

The description is dense but every sentence adds necessary information about usage, behavior, or constraints. It is front-loaded with the critical account requirement, then moves to core functionality and comparisons. While long, there is no filler or redundancy, making it appropriately sized for the tool's complexity.

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

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

The tool's complexity (multi-hop depths, gaps, contradictions, citation URIs, account tiers, time expectations) is fully covered. There is no output schema, but the description explains the return packet (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field). Combined with rich annotations and schema, the description is complete for effective selection and invocation.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds significant value by explaining what each depth value does (quick=single hop, standard=gap recovery + contradictions, thorough=paid iterative hop + contradictions), and clarifies that the question can be broad/multi-part. This extra context justifies one point above baseline.

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

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

The description clearly states this tool performs grounded multi-source research across 1455 structured data sources, decomposes questions into facets, routes to 5,529 tools in parallel, and returns a findings packet. It explicitly distinguishes itself from ask_pipeworx (single lookup) and from open-web search, making its purpose and differentiation unambiguous.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and directly advises using ask_pipeworx for single lookups or breaking/current-news topics. It also covers account requirements and fallback behavior for non-signed-in users, providing clear contextual decision rules.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds value by disclosing return behavior: returns top-N relevant tools with names, descriptions, and full input schemas, ready to call directly with no second lookup. This goes beyond annotations and helps the agent understand the tool's output characteristics.

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 'Find tools' and uses a few sentences to cover purpose, use cases, return value, and strategic advice. While the domain list is somewhat long, it provides useful context and every sentence serves a purpose. It is concise enough for a meta-tool.

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

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

For a discovery tool, the description is complete: it explains what it does, when to use it, what it returns (top-N, with schemas and examples), and even notes the advantage of no second lookup. Given the tool has no output schema, the description adequately covers the return format, making it self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the query concept ('describing the data or task') and mentions 'top-N' which aligns with the limit parameter, but it does not add meaningful detail beyond what the schema already provides. The schema fully documents query and aliases, so the description's contribution is marginal.

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

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

Description clearly states a specific verb+resource: 'Find tools by describing the data or task.' It enumerates multiple domains and explicitly distinguishes itself from other tools by being a meta-tool for discovery. This is distinct from sibling tools like search_wikipedia or search_within, which are not about discovering tool options.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This both states the appropriate context and implies it should not be used when a specific answer is already known.

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 readOnly/openWorld/idempotent/non-destructive; the description adds valuable context: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF, notes the patents API 'soft-fails until reactivated,' and explains the GDELT→GNews fallback. 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?

Long but well-structured: examples front-load intent, followed by sources, return list, and input constraints. Every sentence conveys distinct information, though the density makes it slightly less concise than ideal.

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

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

This is a complex multi-source tool with no output schema, so the description must explain return values and caveats. It enumerates all returned fields (cik, filings, fundamentals, patents, news, LEI), notes the sunsetting USPTO API, and clarifies input handling. This is sufficient for an agent to invoke correctly.

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

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

Schema covers both parameters 100%, including type enum and value format. The description mostly repeats 'ticker or zero-padded CIK' and 'names not supported,' adding examples but no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

Description opens with concrete user phrasings and states it provides a 'full cross-source profile of a US public company in ONE parallel call.' The verb 'profile' plus resource 'US public company' is specific and distinct from siblings like resolve_entity and compare_entities.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name).'

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 destructive nature is already declared via annotations (destructiveHint: true, idempotentHint: true). The description adds 'previously stored' and 'the agent saved earlier' as context, but does not go beyond annotations with detailed behavioral traits like irreversible deletion or handling of missing keys. It is adequate but not rich.

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

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

The description is three sentences, each earning its place: purpose, usage scenarios, and sibling tool pairing. No redundancy or wasted words.

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

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

For a simple single-parameter tool with comprehensive annotations and schema, the description fully covers what the tool does, when to use it, and related tools. No output schema is needed for this straightforward 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?

Schema description coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the mechanism ('by key'). It distinguishes itself from siblings like 'remember' and 'recall' by explicitly pairing with them and focusing on deletion of stored data.

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

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

The description provides explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and names complementary tools ('Pair with remember and recall'), giving clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful process details ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output format ('single text blob ready to drop at site-root/llms.txt'), which goes beyond the annotations and helps users understand actual behavior.

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

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

The description is concise and well-structured: it front-loads the main purpose, briefly explains the process, states the output format, and lists use cases. Every sentence earns its place with zero unnecessary verbosity.

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

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

The tool has only 2 parameters, no output schema, and rich annotations. The description effectively covers purpose, process, output, and use cases. It might lack error-handling or limitation details, but for a simple read-only tool with strong annotations, it is sufficiently complete.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are already fully described. The description adds minimal extra semantics beyond saying 'any URL' and mentioning site-root, but it doesn't elaborate on max_links or any new parameter details, meriting the baseline 3.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL so AI crawlers (ChatGPT, Claude, Perplexity) can index the site cleanly.' This uses a specific verb (generate) and resource (llms.txt file), and the process details (fetch, extract, emit) distinguish it from siblings like ai_visibility_check.

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

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

Provides explicit use cases via 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or exclusions relative to similar tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by specifying the output is clean plain text without markup, that it returns full prose rather than a summary, and that the result is character-capped. This goes beyond what annotations alone provide.

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

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

The description is compact yet comprehensive, using three sentences to convey purpose, usage priority, and parameter behavior. Front-loads the core function, uses parenthetical examples efficiently, and contains no filler or redundant 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?

For a read-only content retrieval tool with three well-documented parameters and no output schema, the description fully covers the necessary context: what it returns, how to request sections, character cap behavior, and its relationship to sibling tools. It is complete for an agent to select 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?

The schema already provides complete parameter descriptions, including ranges and defaults for max_chars and the source of section numbers from get_article_sections. The description adds minimal new parameter-level information, mostly repeating the section behavior already in the schema. Baseline 3 is appropriate given 100% schema description coverage.

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

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

The description clearly states the tool returns the full plain-text of a Wikipedia article by title, explicitly distinguishing it from get_article_summary by noting 'the ACTUAL prose, not just the lead paragraph.' This provides a specific verb, resource, and scope, and references sibling tools for differentiation.

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

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

The description explicitly says to PREFER this over get_article_summary when needing the whole article or a specific section, with example query patterns ('explain X in detail'). It also instructs how to use section numbers from get_article_sections and when to omit section for the full article, providing clear when-to-use and how-to-use guidance.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds concrete behavioral context: 'Cheap, structural-only' and clarifies that it returns headings without prose, which is useful beyond the structured fields. No contradiction found.

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

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

Front-loaded with the core purpose in the first clause, then follows with targeted usage guidance, chaining recommendation, and a performance note. Every sentence earns its place—minimal and efficient.

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

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

Given the single-parameter schema, rich annotations, and presence of an output schema, the description covers purpose, usage, performance, and chaining. It is appropriately complete for a simple, structural-only tool without over-explaining.

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 a clear explanation and example for the title parameter. Description only restates 'by title', adding no meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: returns the section outline/table-of-contents of a Wikipedia article. Clearly distinguishes from siblings with 'without the prose' and references get_article_summary for lead text, establishing a unique scope.

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

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

Explicit when-to-use: long articles needing navigation to a specific section, directly contrasting with 'entire summary'. Names get_article_summary as a chaining alternative. However, it does not specify when not to use or mention other siblings like get_article_extract, making guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it emphasizes 'exact title' matching, notes performance characteristics ('faster + cheaper'), and explicitly lists the returned content. This goes beyond what annotations alone provide, though it doesn't describe error handling for missing titles.

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

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

The description is three sentences, each earning its place: first states the function and performance, second lists return items, third provides usage context and a pointer to an alternative. There is zero fluff 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?

For a simple, one-parameter read-only tool with a rich output schema and strong annotations, the description covers what the tool does, returns, when to use it, and how it compares to alternatives. No additional context seems necessary for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% for the title parameter, so the baseline is 3. The description adds semantic nuance by emphasizing 'exact title' and 'canonical title,' clarifying the precision required. It also contextualizes the title's role in getting a 'standard prose answer.' This extra guidance justifies a score above baseline.

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: 'AUTHORITATIVE summary of a Wikipedia article by exact title' and enumerates the return values: 'lead paragraph, one-line description, thumbnail image, and a few related-content links.' It also distinguishes it from sibling tools like get_article_sections, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you already have the canonical title (got it from search_wikipedia, or it's a well-known entity) and need the standard 'what is X' prose answer.' It also names alternatives and exclusions: 'typically faster + cheaper than search_wikipedia + get_article_sections + scrape' and 'For the full section breakdown use get_article_sections.' This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about the random behavior and return structure (title, introduction text, page ID), which goes beyond what annotations provide. It does not contradict any 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 exactly two sentences, front-loaded with the primary purpose and followed by the return value. Every word earns its place, with no redundancy or fluff.

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

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

For a tool with one optional parameter, complete annotations, and an output schema, this description is sufficient. It communicates the essential purpose, expected output, and random nature, leaving no critical gaps for the agent to make an informed invocation decision.

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 single parameter 'count' has a complete description in the input schema ('Number of random articles to fetch (1-10, default 5)'), so the description need not repeat it. The tool description itself does not elaborate on parameter semantics, but with 100% schema coverage, this is acceptable per the baseline.

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

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

The description clearly states the tool's function: 'Discover random Wikipedia articles for serendipitous learning.' The verb 'Discover' combined with 'random' and 'serendipitous' distinguishes it from sibling tools like search_wikipedia or get_article_extract, which target specific articles. It also states the return payload (title, introduction, page 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?

The description implies use for exploratory discovery ('serendipitous learning') but does not explicitly contrast with alternatives like search_wikipedia or get_article_summary. There is no 'when not to use' guidance or mention of sibling tools, so usage context is only implicit.

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

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

Annotations already convey readOnlyHint and destructiveHint, so the safety profile is covered. The description adds value by detailing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the caller-specific scope, enhancing transparency beyond the structured data.

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

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

Three sentences: purpose, return fields, and usage guidance. Information is front-loaded and each sentence serves a distinct purpose with no filler or redundancy.

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

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

The tool is simple (one optional parameter, no output schema) and the description provides sufficient context: what is returned, the scope ('caller's'), and typical use cases. Combined with strong annotations, there are no significant gaps for an agent to mis-invoke it.

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

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

The single optional parameter include_inactive is fully described in the schema with 100% coverage. The tool description does not add additional meaning about the parameter, so it relies on the schema, which is acceptable per the baseline.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb ('List') and resource ('subscriptions'). It distinguishes itself from sibling mutation tools like subscribe and unsubscribe by focusing on read-only 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?

The description explicitly suggests when to use the tool: to review current monitoring before adding more subscriptions or to find a subscription id to cancel. While it doesn't name specific alternative tools, the context is clear enough for an agent to decide between this list operation and mutation operations.

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

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

Despite sparse annotations, the description fully discloses behavior: rate limiting ('Rate-limited to 5 per identifier per day'), quota ('doesn't count against your tool-call quota'), the claim_token workflow, and feedback handling ('team reads digests daily'). This goes well beyond annotation hints and provides all necessary operational context.

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

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

The description is detailed but well-structured, with clear sections for usage, exclusions, workflow, and limits. Sentences are purposeful and front-loaded with the core purpose. While slightly long, each sentence earns its place and the structure aids comprehension.

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

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

Given no output schema, the description fully explains return behavior (claim_token) and how to use it for follow-up. It covers rate limits, quota, and alternative channels. It is complete for a feedback tool with this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and message specifics ('Be specific... 1-2 sentences typical'). This exceeds baseline.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than asking questions.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds value by disclosing the aggregation source ('derived from CF analytics-engine'), privacy (no PII), and caching behavior ('Cached 5min-1h depending on window'). It also clarifies the data shape (pack, tool, count). This goes beyond the basic safety profile.

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

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

The description is well-structured and front-loaded with the main purpose. The numbered use cases make it scannable, and each sentence adds substantive value. It is slightly longer than necessary, but no information is redundant or wasted.

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

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

With no output schema, the description compensates by stating what is returned (top tools, top packs, total call volume) and the data format (pack, tool, count). It also covers caching and privacy aspects. For a simple read-only tool with one optional parameter, this is sufficiently complete.

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

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

The schema already covers 100% of the parameter with a good description of window semantics (shorter=hot, longer=steady-state). The description adds extra nuance about caching ('Cached 5min-1h depending on window') that informs window selection, plus the use cases imply which window to choose. This exceeds the baseline for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It effectively differentiates from siblings like discover_tools by emphasizing 'what other AI agents are calling on Pipeworx right now,' making it uniquely about trending usage rather than tool discovery.

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

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

Provides explicit use cases: (1) discovering hot data sources, (2) confirming canonical choice, (3) checking alignment with agent needs. These give concrete guidance on when to use the tool. However, it does not name alternative sibling tools or explicitly state when not to use it, slightly limiting the differentiation.

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

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

The description discloses far beyond the readOnly/idempotent annotations by explaining internal checks (Jaccard ≥0.30, partition placeholder filter >20%), the fill-check behavior ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade'), and edge-case outputs like skipped_low_similarity. This is exactly the behavioral context annotations don't provide.

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

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

The description is long and dense, but every section earns its place with labeled concepts (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It could be more scannable with bullet points, but the structure is logical and front-loaded with the core purpose.

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

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

For a complex tool with no output schema, the description covers all critical aspects: modes, inputs, internal logic, response fields (opportunities[], partition_check), fill-check behavior, and related tools. It even explains how to interpret null signals and placeholder filtering, ensuring the agent knows what to expect.

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

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

Schema coverage is 100% with both parameters described, so baseline is 3. The description adds deeper semantic value by explaining what each parameter triggers (e.g., 'walks child markets, checks date-axis/threshold-axis ordering' for event) and provides concrete example slugs like 'fed-decision-may-2026', which 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the method, and further distinguishes three operation modes (no-args, event, topic), making its scope unmistakable and differentiating it from siblings like polymarket_edges.

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

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

The description gives explicit when-to-use guidance: 'event (recommended for a specific market)', 'topic (for cross-event scanning)', and 'Call with NO args for a trending_scan'. It also directs users to 'polymarket_fill_risk' for custom sizing, providing clear alternatives and exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral traits: 1-hour KV caching keyed on knobs, placeholder-slug filters, partition overround mechanics, funnel diagnostics in _diagnostics, Fed bets exclusion from ranking, and a 24h-move warning when the edge may already be priced in. It also explains why segments can be empty via diagnostic counters. This goes far beyond what annotations provide.

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

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

The description is dense and information-rich, with clear section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. However, it is quite long and packs many details (e.g., per-sport alpha values, specific gate thresholds) that may be more appropriately placed in the output schema or documentation. It earns its place technically but sacrifices conciseness.

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

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

Even without an output schema, the description comprehensively details the response structure: 'RESPONSE TOP-LEVEL: by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note... and _diagnostics{...}' It also explains what each opportunity includes (edge_pp_net, kelly_fraction, etc.) and the caching behavior. For a complex tool with 9 parameters and no output schema, this description fills the gap nearly completely.

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

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

Schema coverage is 100% (all parameters have descriptions), so the baseline is 3. The description adds semantic context by explaining how the knobs interact: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also clarifies a subtle behavior: partition arbs always return kelly_fraction_half=0 at the parent level, so min_kelly doesn't filter them but min_partition_leg_kelly does. This adds value beyond the schema.

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

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

The description opens with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the tool's intended use ('what should I bet on today') and differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreements and the three model-family segments.

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 strong contextual guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains when the tool is appropriate and how knobs like min_liquidity/max_spread_pp gate tradeability. However, it doesn't explicitly state when NOT to use it or name direct alternatives (e.g., polymarket_arbitrage for pure arbitrage), so it stops short of full when/when-not clarity.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals significant behavioral details: snapshots are written on cache-miss so gaps mean no scan; history is bounded by 60-day TTL; decay computed from daily closes not intraday; and the response structure including expired opportunities and snapshot_dates. This goes well beyond what annotations provide.

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

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

The description is dense but well-structured, with distinct sections for purpose, args, response, and limits. Every sentence provides useful information, though it is quite long for a two-param tool. It is front-loaded with purpose and organized, but not as lean as it could be.

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 completely explains the return shape (tracked[], expired[], snapshot_dates[]) with field-level detail. It also covers limitations (TTL, snapshot start, daily closes) and the behavioral quirk of snapshot gaps. This is comprehensive for a complex time-series tool.

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

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

The input schema already fully describes both parameters (days with default/clamp, window with enum values). The description repeats this information in the Args section without adding meaningfully new details. Since schema coverage is 100%, a baseline of 3 is appropriate; there is no added value like parameter interactions or format specifics.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the explicit question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence and decay, not just current edges.

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

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

The description provides clear context for when this tool is appropriate: comparing fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or exclusions, but the focus on persistence/decay makes the use case clear. It lacks an explicit 'use this instead of X' statement, so it does not earn 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?

The description discloses behavior far beyond the annotations: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that partial basket fills convert an arb into an unhedged directional position—critical risk context. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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 extremely dense; every sentence carries actionable detail. It is front-loaded with the core purpose and then structured by mode. Slightly verbose, but the complexity of two modes and risk guidance justifies the length.

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

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

Given no output schema, the description enumerates return values for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs[], etc.), covers all four parameters with mode-specific meaning, and includes practical risk warnings. It is fully self-contained for a complex 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?

Though the schema has 100% coverage, the description adds substantial semantics: explains how size_usd is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional, shares per leg), defines the default side logic in basket mode, and mentions clamping. This is meaningful addition over the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal detection or theoretical edge.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also contrasts single-market vs basket modes, giving clear context for choosing between them.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds extensive behavioral context: compatibility_warning triggers with specific conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the crucial note about non-equivalent bet shapes. It discloses edge cases (e.g., matched_pairs:0 scenarios) that are vital for correct interpretation. This significantly exceeds the structured annotation coverage.

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

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

The description is lengthy but deliberately structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and densely packed with necessary details. Every sentence contributes to understanding the tool's behavior, warnings, and response semantics. The length is justified by the tool's complexity, though it could potentially tighten the final redundant caution.

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

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

Given the tool's complexity and the absence of an output schema, the description fully covers response components (leg-by-leg prices, spread[], compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and their meanings. It also provides real-world expectations about how often the tool yields tradeable signals. This is sufficient for an agent to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100% with property descriptions for all three parameters, so the baseline is 3. The description adds value by explaining the two-mode interaction: how topic auto-fetches a pre-mapped event and how explicit kalshi_event_ticker/polymarket_event_slug override each side of the pairing. This clarifies relationships between parameters beyond the schema's isolated 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 opening sentence clearly defines the tool as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' establishing a specific verb+resource purpose. It distinguishes itself from sibling tools by explicitly naming both venues and explaining the spread calculation, which is unique among the siblings listed (e.g., polymarket_arbitrage, polymarket_edges).

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

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

The description provides clear context for two modes: pre-mapped topic shortcuts versus explicit ticker/slug pairings, explaining when each is appropriate. It also warns that most pre-mapped topics return compatibility_warning, which guides when results are not meaningful. However, it does not explicitly mention alternative sibling tools or exclusion criteria relative to those tools, so it stops short of a 5.

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

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

Annotations already convey read-only and non-destructive behavior. The description adds valuable behavioral context beyond annotations by explaining the scoping mechanism (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (retrieve vs. list). This is useful for an agent to understand the tool's operational boundary, though it could go further with details about missing-key behavior.

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

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

The description is two sentences long, front-loaded with the primary action, and includes concrete examples and necessary caveats (scoping). It avoids redundancy with the schema and annotations, earning its length. No filler or 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers the functionality: both retrieval and listing modes, the source of saved values (via remember), and scoping context. It is complete enough for an agent to use the tool correctly without additional 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?

The input schema already provides 100% coverage of the single optional parameter 'key' with a clear description ('omit to list all keys'). The tool description repeats this behavior but does not add significant new meaning beyond the schema. Thus the baseline of 3 applies, as the description doesn't compensate further.

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

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

The description clearly states the tool's function: retrieve a value saved via remember, or list all saved keys when key is omitted. It distinguishes itself from sibling tools (remember and forget) by explicitly positioning itself as the retrieval counterpart, and the verb 'retrieve' is specific and action-oriented.

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

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

The description provides clear usage context, such as 'look up context the agent stored earlier' and concrete examples (ticker, address, research notes). It also gives indirect guidance about when to use it versus alternatives by mentioning 'pair with remember to save, forget to delete,' though it doesn't explicitly state exclusions or when not to use it.

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

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

Despite the readOnlyHint annotation, the description transparently discloses that mark_read:true causes a side effect (flags events read, affecting subsequent calls). It also explains the persisted feed and polling behavior, adding material context beyond the annotations. This is not a contradiction because the primary operation is read-only and the side effect is clearly flagged as optional.

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

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

Four concise sentences, each earning its place: purpose, return format, filtering flags, and polling/alternate access. Front-loaded and free of fluff.

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

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

For a read-oriented tool with five optional parameters and no output schema, the description covers return fields, filtering, read-state management, polling suitability, and an alternative access method. It provides sufficient context to invoke correctly without missing critical details.

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

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

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by giving a concrete example for type ('sec_8k'), clarifying the consequence of mark_read ('so the next call only shows newer ones'), and reinforcing that since accepts ISO timestamps. This extra semantic layer justifies a 4.

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

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

The description opens with a clear verb and resource: 'Pull fired events from your subscription feed.' It distinguishes itself from sibling tools by focusing on subscription alerts, the persisted feed, and its own retrieval semantics. The return fields (source, citation_uri, raw payload) further solidify the 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?

Context is clear: the tool is for retrieving recent alerts and supports polling ('Polls work fine'). It mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools. The absence of exclusions or a direct 'when-not-to-use' keeps it from a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant operational detail: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return structure. This goes well beyond annotations and sets correct expectations.

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

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

Dense but efficient: starts with query examples, then states the core function, lists sources, and closes with an alternative. No fluff; every sentence adds 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?

For a tool with no output schema, the description fully covers the return shape (changes[] grouped by source, total_changes, citation URIs), the supported time windows, the fallback behavior, and the limitation (patents soft-fail). This is a complete operational picture for a complex aggregation tool.

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

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

Schema covers all three parameters at 100%, so baseline is 3. The description adds value by explaining `since` formats ('ISO date' or 'relative shorthand') with examples and recommending '30d' or '1m' for typical monitoring. This extra guidance justifies a 4.

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

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

Clear verb ('change feed') and resource ('company'), with concrete example queries that illustrate the intent. Explicitly distinguishes itself from entity_profile, which covers static profiles.

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

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

Provides explicit 'when to use' via example natural-language queries, and an explicit alternative ('Use entity_profile instead when you want the static profile...'). Also explains fallback behavior and window syntax, giving clear context for selection.

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

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

Annotations already mark this as non-read-only and idempotent. The description adds context about key-value scoping by identifier, 24-hour retention for anonymous sessions, persistent memory for authenticated users, and the ability to delete via forget. 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 five sentences, all purposeful, with the first sentence front-loading the purpose. It includes examples and persistence details, but each 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?

For a simple key-value write with two fully described parameters, the description covers discovery triggers, retention policy, and lifecycle pairing. No output schema exists, but return value is not critical for deciding when to use this tool.

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

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

The input schema covers both key and value with examples at 100% coverage, so the baseline of 3 applies. The description repeats the key-value concept but does not add new parameter-level detail beyond the schema.

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

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

The description opens with 'Save data the agent will need to reuse later,' clearly stating a specific verb and resource. It also distinguishes the tool from siblings recall and forget by explicitly pairing with them for retrieval and deletion.

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 states 'Use when you discover something worth carrying forward' and explains the benefit of avoiding future lookups. It also names recall and forget as complementary tools and clarifies persistence differences for authenticated vs anonymous sessions.

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

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

Beyond the annotations (readOnly=true, idempotent=true), the description discloses important behavioral traits: it degrades gracefully ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicitly handles unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'), and reveals it cascades through multiple endpoints. This is valuable context that annotations do not provide.

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

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

The description is dense but a bit long. It opens with many example queries (which are illustrative but not strictly necessary) before stating the actual purpose. All sentences provide useful information (supported types, fallback behavior, source labeling), so each earns its place. Still, it could be more concise by moving the examples after the main 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 tool with no output schema, the description thoroughly explains return values: it lists the identifiers returned for company (CIK, ticker, company_name, LEI, FIGI) and drug (RxCUI, ingredient, brand), how sources are labeled, what happens on failure, and the 'unresolved' field. It even notes that it replaces multiple manual lookups, giving the agent complete context for when and what to expect.

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

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

Schema description coverage is 100%, with both `type` and `value` already well-documented in the schema (including examples like 'AAPL' and 'ozempic'). The description largely repeats this parameter info (e.g., 'accepts ticker, CIK, or company name as input') without adding new constraints or meanings. It does add context about output behavior, but that's not parameter semantics. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb ('resolve'), a resource ('entity' or name-to-ID mapping), and further distinguishes itself by listing supported types ('company', 'drug') and noting it replaces manual lookups. This differentiates it from siblings like entity_profile or compare_entities, which work with already-resolved entities.

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

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

The description gives an explicit when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use it (when you already have an ID that other tools require) by stating it provides IDs 'other tools require as input.' However, it does not explicitly name alternatives or provide a 'when not to use' section, so it falls short of the top score.

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, open-world, and non-destructive. The description adds valuable behavioral details: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. It also reveals the 'first entry as subject' convention. No contradictions with annotations.

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

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

Three sentences, front-loaded with purpose, then process, then usage context and return format. Every sentence contributes value with no repetition 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?

No output schema exists, so the description compensates by explaining the return structure (ranked list with score, confidence, signal density). It covers the multi-entity comparison process and the optional API key for Anthropic models, though it does not detail error behavior or rate limits, which are less critical for a read-only, idempotent 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%, so baseline is 3. The description adds meaningful semantics for the 'entities' parameter by specifying the first entry is the subject and the rest are competitors. This goes beyond the schema's basic 'array of entities' description, providing narrative context that affects how the tool interprets input.

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

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

The description states a specific verb (Compare) and resource (AI visibility across multiple entities side-by-side), and clearly distinguishes from siblings by explaining it probes with ai_visibility_check and ranks results. This differentiates it from the single-entity ai_visibility_check tool and generic compare_entities.

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

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

Provides clear context for when to use it (competitive AI-marketing audits) with a concrete example query. It does not explicitly name alternatives or when not to use it, but the 'side-by-side' comparison and mention of the underlying probe make the intended use clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This adds significant operational context without contradicting annotations.

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

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

The description is information-dense yet well-structured: it opens with the tool's core purpose, then usage guidance, followed by a compact list of return fields, ecosystem scope, and failure behavior. Every sentence contributes value, and the length is justified by the composite nature of the tool.

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

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

With no output schema, the description compensates by listing the exact fields in the summary block, mentioning per-advisory details and links, and clarifying the partial failure behavior. It covers the full scope of what an agent needs to know about invoking and interpreting results.

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

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

The input schema already provides full descriptions for both `package` and `version`, including scoped package acceptance and default behavior. The description does not add extra parameter semantics beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly identifies this as a composite check for adding npm packages, specifying the exact data sources (deps.dev and bundlephobia) and the types of information gathered (license, advisories, bundle size, etc.). It distinguishes itself from sibling tools by scoping to the npm ecosystem and explicitly mentioning what the tool does in one call.

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 usage triggers ('is X safe / popular / small' or 'what does adding lodash cost me') and offers a clear alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This tells the agent both when to use this tool and when not to.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable context: English-only search (with translation advice), cost/performance comparison to web scraping, and coverage of '~7M English articles updated continuously.' This goes beyond annotations and helps set expectations.

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

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

The description is well-structured and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH...'). Every sentence serves a purpose: usage context, examples, return-value summary, chaining suggestions, and rationale. It is concise given the amount of useful information packed in.

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

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

The tool is simple, has an output schema, and strong annotations. The description covers when to use it, its limitations (English-only, query format), and how to extend it with chaining. It leaves no critical gap for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful detail for the query parameter: it warns that non-English queries return 0 hits and advises translating to English keywords. It also provides examples of good queries. The limit parameter is not elaborated, but the schema already describes it; the added query guidance justifies a 4.

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

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

The description clearly states the tool's function: 'Returns matching Wikipedia article titles, snippets, page IDs, word counts.' It also distinguishes itself from web search and references sibling tools like get_article_summary and get_article_extract, making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH for general-knowledge / encyclopedic questions' and gives specific examples (government composition, officeholders). It also explains when to chain with get_article_summary or get_article_extract, providing clear when-to-use guidance and alternatives.

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

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

The description discloses key behaviors beyond annotations: truncation at 200K chars (with a flag), overlapping 500-char windows, BGE-base-en embeddings with cosine similarity, and that every passage includes an offset for verifiability. This adds significant context to the readOnly/idempotent hints.

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 detailed but every sentence adds value: purpose, use case, truncation behavior, algorithm, and pairing with a sibling tool. It is front-loaded with the core action and efficiently structured with semicolons and examples, earning its length.

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

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

Given there is no output schema, the description adequately covers return values (passages with character offsets and similarity scores). It also explains the technical specifics (window size, embedding model, truncation) and provides a clear use case, making the tool fully understandable for an AI agent without further 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 description coverage is 100% for all three parameters, so the baseline is 3. The description adds minor context (e.g., 'text you already pulled' as a usage nuance, 'top-N passages' reinforcing the limit parameter), but does not materially extend the parameter meanings provided by the schema.

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

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

The description clearly states the tool's function: semantic search inside a previously fetched text, returning top-N passages with offsets and scores. It distinguishes itself from siblings like search_wikipedia (external search) and ask_pipeworx_grounded (grounded QA) by emphasizing it operates on a passed-in text.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool ('Pairs with ask_pipeworx_grounded') and explains the workflow: fetch with the gateway, then ground over passages. This directly informs when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable behavioral context: the OAuth requirement, the return of a subscription id, SMS phone verification, and the 10/day cap. It also details webhook signing and auto-disable behavior, which is not trivial. No contradiction with annotations exists.

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

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

The description is dense but well-structured, with clear sections for types and delivery. Each sentence serves a purpose: purpose, auth, supported types, delivery. It could be slightly more scannable, but it avoids fluff and is front-loaded with the core purpose.

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

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

For a complex tool with nested objects and no output schema, the description is exceptionally complete. It covers all supported types, delivery channels, authentication prerequisites, the return value, and even edge cases like webhook signing secret and auto-disable after 10 failures. The agent has enough to invoke correctly without guessing.

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 significant meaning by providing concrete examples for each type: sec_8k items code meaning ('5.02' = officer change), polymarket_edge topic example ('fed'), fred_series via series_id, and delivery semantics like verified phone and 10/day cap. This goes beyond the schema's generic 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 a specific verb 'Create' with a clear resource: 'proactive monitoring subscription to a live-data event stream.' It also distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by clearly stating its unique function. The return value ('subscription id') further clarifies the 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?

It states a critical prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also explains delivery channels and how to consume the feed via recent_alerts or GET alerts.json, effectively distinguishing when to use this tool versus the feed. However, it lacks an explicit 'when not to use' or direct comparison to sibling tools like list_subscriptions.

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, open-world. Description adds that results are 'drawn from the live catalog of thousands of tools', implying dynamic output, and explains it returns suggestions with exact tool call shapes. 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 front-loaded with user query examples and then explains output, parameters, and usage. It is a single dense paragraph but each sentence contributes useful information; could be slightly trimmed but remains structured and readable.

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

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

For a simple read-only tool with no output schema, the description fully explains what it returns (category-bucketed questions with exact tool + argument shape), the optional topic parameter, and the intended use case. It even mentions the live catalog and categories covered.

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

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

The schema description already fully documents the 'topic' parameter with allowed values and omission behavior. The description merely repeats examples ('finance', 'pharma', 'betting') and 'topic' usage without adding new semantic detail; hence baseline 3.

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

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

The description clearly states the tool helps an agent discover what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shape. It distinguishes itself from sibling meta-tools like ask_pipeworx and discover_tools by positioning itself as the FIRST onboarding entry point.

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 FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides clear guidance on when to invoke and even suggests parameter usage (call with no arguments for full spread, or pass topic to focus).

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

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

Discloses critical behavior beyond annotations: ownership enforcement, deactivation instead of deletion, and impact on historical events via recent_alerts. Aligns with destructiveHint=false and idempotentHint=true without contradiction.

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

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

Two concise sentences, front-loaded with the action, and every clause adds value. No wasted words.

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

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

For a simple one-parameter tool, the description fully covers purpose, constraints, side effects, and relationship to recent_alerts. Output schema not needed; context signals confirm low complexity and full parameter coverage.

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 description adds little beyond the schema. It reinforces that id is the subscription id but does not provide new semantic details beyond what the schema already states.

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 specific verb 'cancel' and resource 'subscription'. Distinguishes from siblings subscribe and list_subscriptions by stating the action and object. Ownership enforcement adds precision.

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?

Clear context: use to cancel a subscription. The ownership constraint ('only cancel your own') is an important usage rule. Does not explicitly mention alternatives or when not to use, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond by detailing the return verdicts, the fast path for company-financial claims, the fallthrough to a grounded pipeline, and the crucial semantic distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found). It also warns callers not to treat 'could_not_verify' as evidence, which is critical behavioral context.

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

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

The description is long but highly structured: trigger phrases, use case, sub-path explanations, return values, and an 'IMPORTANT' callout. While slightly verbose, every sentence carries meaningful information and the critical warnings justify the length. It could be tightened, but the organization makes it easy to parse.

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

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

With no output schema, the description compensates fully by explaining the set of possible verdicts, the return of a grounded/structured value with a citation, reasoning, and error semantics. It also covers the two verification routes and the confidence/edge cases. For a tool with two parameters and no output schema, this is a complete and self-sufficient 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?

The schema already fully describes both parameters (100% coverage), but the description adds substantial value: it clarifies the tolerance_pct default ('implied by wording, capped at 5'), shows an example override for hallucination detection, and helps the agent decide when to set it. The claim parameter is illustrated with realistic examples, exceeding what the schema alone provides.

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

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

The description opens with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by noting it 'Replaces 4–6 sequential calls' and describes two distinct verification paths with exact detail, making the tool's scope and purpose unmistakable.

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

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

Directly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further gives guidance on claiming company-financial vs. other claims and explains the meaning of 'could_not_verify' versus 'unsupported', including that the former must not be shown as evidence. This is explicit, actionable usage direction.

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