Caniuse

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: default model is free Workers AI Llama-3.3-70b, passing _apiKey probes Anthropic and incurs direct costs, and return format is specified. 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?

Four sentences, each earning its place: core function, default/config option, return format, and use cases. Front-loaded with the primary purpose, 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?

Despite no output schema, the description specifies return fields ({score, confidence, signals, raw_response} + combined view), explains the default model and optional API key, and gives use cases. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches meaning for key parameters: 'models' defaults to Workers AI unless _apiKey is provided, and _apiKey carries cost implications for Anthropic calls. This goes beyond the schema's basic parameter 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 ('Probe') and resource ('LLMs') and clearly defines the output ('score visibility (0-100) per model'). This distinguishes it from sibling tools like ask_pipeworx or deep_research, which serve different purposes.

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

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

The description lists explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use the tool or name alternatives, but the context is clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals that the tool automatically reroutes to the appropriate specialized tool, fills arguments, and returns a structured answer with pipeworx:// citation URIs. Also notes it works on every tier and is a fast single call, adding useful behavioral context not conveyed by the annotations alone.

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

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

The description is long but well-structured and front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. It packs examples, alternatives, and scope into logically grouped sentences without redundancy. Slightly dense but every sentence adds value, so a high score is warranted.

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 meta-tool that routes to thousands of sources, the description covers purpose, usage triggers, alternatives, behavioral details, and includes concrete examples. It also clarifies its role in breaking-news scenarios. There is no output schema, but the description states it returns a structured answer with citations, mitigating the need for further return-value 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 input schema already fully describes the main parameter with aliases and a clear description. The description adds substantial usage examples but no additional parameter-level semantics (e.g., formatting, constraints, or clarification that the tool fills arguments on the user's behalf). Thus baseline 3 is appropriate with no meaningful extra parameter detail.

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

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

The description crisply states the tool's role as a primary entry point for factual questions about real-world data. It explicitly says 'PREFER OVER WEB SEARCH' and describes routing to 5,529 tools, returning structured answers with stable citation URIs. It also distinguishes itself from sibling tools by naming alternatives (ask_pipeworx_grounded, deep_research) and their specific use cases.

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

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

Provides explicit when-to-use guidance: lists trigger phrases ('what is', 'look up', 'find') and example queries, says 'START HERE for most questions', and gives clear step-up instructions for grounded research or deep research. Also addresses when web search might be a fallback but says to prefer 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?

The description goes beyond annotations by explaining the experimental nature, the live testing of candidate routing improvements, the current lack of an active candidate, and that it is a full working router (falls back to nothing). This is rich behavioral context that helps the agent understand exactly what to expect.

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 sentences, each earning its place. The description is front-loaded with the essential beta designation, then details the experimental process, current state, and usage instruction. No wasted words.

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

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

Given the annotations (read-only, idempotent, open-world), the schema (six params with aliases fully described), and no output schema, the description sufficiently covers the experimental context, usage, and comparison with the stable tool. It mentions 'same response shape' as ask_pipeworx, which is enough, but could have briefly stated what the response contains for extra completeness.

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

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

Schema description coverage is 100%: the 'question' parameter is well described and all six aliases are documented. The description adds only 'same arguments as ask_pipeworx,' which does not enhance the semantic understanding beyond what the schema already provides. A baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the experimental edge, though it does not explicitly state 'ask a question and get an answer'—that is implied by the name and context.

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

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

It explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and it notes the current state (no active candidate, matches ask_pipeworx exactly). It also mentions results are compared to the stable router, implying stable use should go to ask_pipeworx, but it does not give an explicit 'when not to use' statement.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing the exact return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}), the refusal reasons, and the grounding guarantee ('using ONLY what the tool result contains'). This adds critical context about how the tool behaves and what to expect, with no contradiction to 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 but well-structured, with each sentence providing distinct value: purpose, routing mechanism, output contract, usage guidance, and cost tradeoff. It is front-loaded with the key differentiator and contains no filler, making it both comprehensive 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?

The description covers the tool's behavior, output format, failure modes, and usage context. Given no output schema, it fully specifies the return contract and refusal handling, while also addressing when to use the alternative tool. This makes it complete for an agent to decide and invoke correctly.

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

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

The input schema fully describes all parameters (100% coverage), including aliases and the 'question' parameter meaning. The description adds no additional parameter-level semantics, so it meets the baseline of 3 for high schema coverage without needing to compensate.

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 immediately states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from ask_pipeworx by emphasizing grounded extraction. It clearly specifies the action (answers questions) and the resource (routed via 5,529 tools across 1,455 sources), making the purpose unambiguous and distinct from sibling tools.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to avoid it ('prefer ask_pipeworx for casual lookups'). It also mentions the cost tradeoff (one extra LLM call), aiding the agent in making appropriate choices.

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

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

The description goes far beyond the readOnlyHint annotations by explaining low-confidence short-circuiting, closed/dead market status, wide-spread flags, resolution-rule risk, and fallback behavior for news sources. It also details the resolver contract and parent_event extractor, providing substantial behavioral context that annotations do not cover.

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 well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a clear opening summary. While extensive, the detail is relevant and organized, making it more structured than unnecessarily verbose.

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 (classifiers, fan-outs, response shapes, resolver contract, edge cases), the description covers all critical aspects: input format, fan-out strategies, output structure, safety behavior, and resolution risk. This is sufficient for an agent to understand and invoke the tool correctly without an output schema.

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

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

The schema already describes all three parameters (market, depth, include_raw) with 100% coverage. The description adds minimal parameter semantics beyond the schema—it restates the market input types but does not elaborate on depth or include_raw behavior, so it does not exceed the baseline for well-covered schemas.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', which clearly states the verb (research), resource (Polymarket bet), and method (pulling Pipeworx data). It further details the pipeline (resolve, classify, fan out, return evidence packet) and provides classifiers and examples, making the tool's purpose distinct from sibling tools 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?

It explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear when-to-use guidance. However, it does not mention when not to use it or name alternatives, so it misses explicit exclusions.

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

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

The description goes far beyond the annotations by revealing the data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and the return format with citation URIs. This adds valuable behavioral context that the annotations do not cover, such as underlying data provenance and ordering 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 long but information-dense. It front-loads with user query examples and then systematically covers preference, type-specific details, sorting, and output format. While some redundancy exists (e.g., 'ONE parallel call' and 'Replaces 8–15 sequential lookups'), each sentence contributes to the tool's understanding, so it earns its place.

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

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

Given the absence of an output schema, the description covers essential return information (paired data, citation URIs), data sources, and sorting. It lacks explicit error handling or edge-case behavior (e.g., invalid tickers), but overall it provides a comprehensive picture for a tool of 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?

Although the schema already documents both parameters, the description enriches them by specifying what metrics each 'type' returns (revenue, net income for company; adverse events for drug) and provides concrete examples for 'values' (tickers/CIKs, drug names). This adds meaning beyond the schema's generic descriptions, including details like off-calendar handling.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with concrete examples like 'X vs Y' and 'rank these companies.' It distinguishes itself from sequential lookups by emphasizing a single parallel call, and details type-specific data sources, 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' which provides a clear directive for when to use this tool. It also lists example queries to signal appropriate usage, though it does not explicitly name sibling tools or state when not to use it beyond the comparison context.

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

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

Beyond the read-only/idempotent annotations, the description discloses substantial behavioral detail: account requirement, parallel facet routing, findings packet structure with gaps[] and contradictions[], resolvable citations via citation_uri, semantic excerpting, latency expectations, and the fact that it is not open-web search. This context is not present in annotations and greatly helps the agent predict 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 long (over 250 words) but dense with essential information. It is logically structured, starting with account requirements, then core purpose, alternatives, behavior, and limitations. While not concise, it avoids fluff and every sentence contributes useful guidance. It could be improved by tighter organization, but it is not wasteful.

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 return values (findings packet, gaps[], contradictions[], hop field, citation_uri), expectations (latency), limitations (empty gaps for uncatalogued topics), and prerequisites (auth). It also differentiates from many siblings, making it completely contextual for an agent navigating a large toolset.

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 describes both parameters with 100% coverage, including detailed semantics for the depth enum. The description's mentions of depth behavior largely mirror the schema, adding little new meaning. Since schema coverage is high, a baseline of 3 is appropriate—the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with a specific verb (research) and resource (structured data). It explicitly distinguishes itself from open-web search and from the sibling tool ask_pipeworx by describing its decomposition and parallel routing behavior. This leaves no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with ask_pipeworx for single lookups and breaking news. It also states account requirements and a fallback alternative if not signed in. These clear usage boundaries are superior to typical tool descriptions.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior. The description adds valuable context about the return payload: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output format and workflow implications beyond the annotations.

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

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

The description is slightly long but every sentence contributes: the opening verb+resource, the use-case list, the return format, and the strategic directive. The list of domains is arguably necessary to convey scope. It is well-organized 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 discovery tool with no output schema, the description adequately covers what the tool returns (top-N with schemas), how to invoke it (natural language query), and when to use it (first step in a multi-tool environment). It does not enumerate every possible domain, but the examples cover a wide range and the query accepts any description, so 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?

The input schema is fully documented with 100% coverage, including aliases (query, q, task, search, description) and limit semantics. The description adds little beyond the schema—it simply reinforces that the query is a natural language description. Since schema coverage is high, 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 purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, FRED, etc.) and explicitly differentiates from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This makes it distinct from search/data-retrieval tools.

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

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

The description provides 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.' It also implies when not to use it by noting 'not just one answer,' steering users away from direct data lookups.

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

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

The description discloses significant behavioral traits beyond annotations: it fans out across multiple sources, soft-fails on patents due to API sunset, uses a fallback chain GDELT→GNews, returns specific fields, and emphasizes parallel execution. Annotations declare readOnly/idempotent, and the description adds context 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 long but information-dense; the multiple query examples are somewhat repetitive but serve to illustrate trigger patterns. It fronts the core purpose with examples, then efficiently details return fields and caveats. Slightly over-stuffed but every sentence earns its place.

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

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

With no output schema, the description takes full responsibility for explaining return values and behavior. It enumerates exactly what is returned (CIK, filings with URIs, fundamentals with field names, patents, news, LEI) and covers limitations and fallbacks, making it highly complete for agent use.

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

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

Schema coverage is 100% and the schema already contains rich descriptions for both parameters, including examples and the caveat about names. The description repeats this information nearly verbatim ('Pass ticker AAPL or zero-padded CIK...'), adding no new semantic value beyond 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 defines the tool as a 'full cross-source profile of a US public company in ONE parallel call' with a specific verb and resource. It distinguishes itself from siblings by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups and directing name-only queries to resolve_entity.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states the alternative for name-only inputs: '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?

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description's incremental value is modest. It adds that the record is 'full' and provides example IDs, but does not disclose additional behaviors like error handling or data freshness.

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

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

The description is a single, front-loaded sentence with no wasted words, effectively communicating purpose and parameters.

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, a one-parameter lookup with a full output schema, the description is mostly complete. It omits edge-case behavior (e.g., unknown feature IDs), but the output schema and annotations cover the remaining context.

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

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

With 0% schema description coverage, the description compensates by explaining that 'name' is a feature ID and providing examples. This gives the agent sufficient meaning to invoke the tool correctly, though it could add syntax or formatting details if needed.

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 retrieving a full caniuse record for a given feature ID, with concrete examples like 'css-grid' and 'fetch'. This specifies a distinct resource and scope, distinguishing it from any sibling search tools.

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

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

The description implies the tool is for fetching comprehensive feature data, but it does not explicitly state when to use it over alternatives like search or search_within, nor does it mention any exclusions. Usage context is present but not detailed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the core behavioral traits. The description adds usage context but no additional behavioral details (e.g., irreversibility, behavior for missing keys), so it adds marginal value beyond annotations.

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

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

The description is two sentences, front-loaded with the action, and includes only essential usage guidance. Every word serves a purpose, with no redundancy or filler.

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

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

For a simple tool with one parameter and strong annotations, the description covers purpose, usage, and complementary tools. It lacks edge-case behavior like missing-key handling, but this is not critical given the tool's simplicity and annotation support.

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 for the single 'key' parameter, with a description 'Memory key to delete'. The tool description mirrors this by saying 'by key' without adding new constraints, formats, or examples, so it does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the action 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by naming complementary tools 'remember' and 'recall', making its role in the memory toolkit obvious.

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 guidance on when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also pairs with 'remember and recall', but it does not explicitly state when not to use the tool, so it lacks exclusions.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds behavioral detail: it fetches the page, extracts title/description/key links, emits markdown, and returns a single text blob. This goes beyond the annotations and helps the agent understand what the tool does without contradicting the 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?

Three sentences, front-loaded purpose, no redundant phrasing. The description is tight and structured.

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

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

The tool has two parameters, no output schema, and clear annotations. The description explains the output format (standard llms.txt markdown, single text blob), the process, and use cases. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema covers 100% of parameters with descriptions. The description adds an example of 'url' ('https://example.com') and clarifies the output is a text blob, but it doesn't add meaning beyond the schema's max_links description. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource, and further describes the process (fetch, extract, emit) and output format. It differentiates from sibling tools like scan_competitor_ai_presence by focusing on generating the file rather than simply checking presence.

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

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

The description provides concrete use cases ('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'), which gives clear context for when to invoke it. It doesn't explicitly name alternative tools or exclusions, but the use cases are 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 traits, so the description doesn't need heavy safety disclosure. It adds specific context about the output (all browser IDs and recent version strings) but doesn't discuss pagination or data freshness—acceptable given the annotations.

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

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

The description is a single sentence that front-loads the main purpose, includes practical example IDs, and integrates the usage hint naturally. No redundant wording.

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 parameterless, read-only listing tool with an output schema, the description adequately conveys the scope and output, and it references the downstream tool. It is complete enough for an agent to 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description confirms there is nothing to configure by omitting parameter details. Baseline 4 applies for parameterless tools.

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 all browser IDs tracked by caniuse with their recent version strings, using a specific verb ('Return') and resource ('browser IDs'). It further distinguishes itself by referencing the `support` tool, clarifying its role among siblings.

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

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

The instruction 'use IDs with the support tool' provides explicit guidance on when to use this tool (to obtain browser IDs for use with support). It does not spell out exclusions or alternative scenarios, but for a parameterless list tool, the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds the return field list and default behavior (active only), which is valuable because 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?

Two sentences, front-loaded with purpose. The second sentence gives actionable usage guidance without redundancy 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?

For a simple one-parameter read-only tool, the description covers purpose, return fields, and usage context. No output schema exists, but the field list compensates for this gap.

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

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

The single parameter include_inactive is fully documented in the schema (coverage 100%), and the description adds little beyond matching the 'active' default. 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from siblings like subscribe/unsubscribe by focusing on the listing 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 provides explicit use cases: 'review what you're monitoring before adding more' or 'find an id to cancel.' It does not explicitly name alternatives, but the context strongly implies it is for read-only inspection before mutation.

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

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

Annotations provide no hints (all false), so description carries full burden. It discloses behavioral traits: returns claim_token for anonymous filings, supports later retrieval of resolution status, rate-limited to 5/day, free, and not quota-counted. This goes beyond schema and annotations.

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

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

The description is a dense single paragraph with no wasted sentences, but it packs many clauses. It is front-loaded with purpose, then flows through usage, exclusions, claim token, and limits. Slightly verbose but appropriately sized for the tool's nuance.

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

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

No output schema exists, so description must cover return values; it mentions claim_token and reading status, enough for a feedback tool. It also covers context parameters and rate limiting. Could specify exact response shape, but given simplicity, it's adequate.

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

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

Schema has 100% coverage for all 4 parameters including enum explanations, so baseline is 3. Description adds useful guidance: the claim_token round-trip workflow, instructing not to paste end-user prompts, and emphasizing specificity in message. This extra context pushes it to 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 states a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by scoping to Pipeworx connection tools and explicitly contrasts with alternative MCP servers, making the purpose specific and unambiguous.

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

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

Explicitly lists when to use: bug, feature/data_gap, praise. Gives exclusion: do not report tools from other MCP servers, and offers a test ('Pipeworx tool names are the ones this connection lists'). Also includes claim_token workflow and rate limits, providing a complete usage playbook.

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 traits. The description adds useful context beyond annotations: it mentions caching behavior (5min-1h), data provenance (CF analytics-engine), and privacy (no PII). This enriches the agent's understanding of what to expect. 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 appropriately sized—a single-purpose tool with one optional parameter gets a dense but not bloated description. It front-loads the core function, then lists use cases and operational details. Every sentence contributes; no redundancy. Slightly long but justified by the useful context.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is remarkably complete. It explains what is returned, window options and their implications, caching behavior, data source, and privacy. The annotations cover safety, so this description fully equips an agent to select and invoke the tool.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining how the window parameter affects results ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). This goes beyond the schema's simple enum listing, helping the agent choose appropriate values.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume over a recent window. The verb 'Returns' plus the specific resource (top tools/packs/call volume) makes the purpose explicit. It also distinguishes itself from siblings by focusing on trending/aggregate agent behavior rather than individual 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?

The description lists three concrete use cases: discovering hot data sources for current events, confirming a popular tool is canonical, and seeing alignment with agent needs. This provides clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description goes beyond these by detailing the fill check (realizable_edge_pp ≤ 0 means do not trade), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), and the exact response shape. 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 longer than usual, but it is well-structured with bold labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and each sentence adds value. It is front-loaded with the core action and then organizes details, though some repetition of 'partition_check' could be tightened.

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 essential aspects: modes, response structure, filters, fill-check behavior, cross-event logic, and alternatives. It leaves no major gap in understanding how to invoke or interpret 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 descriptions for event and topic are basic, but the explanation extends them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), mode-specific behavior, and what the tool does with each parameter. This adds significant meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states both the action and the technical method, distinguishing it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

It provides explicit usage modes: 'Call with NO args for a trending_scan', 'pass `event` for a single-event check', and '`topic` for a themed cross-event scan'. It also gives an explicit alternative: 'For custom sizing use polymarket_fill_risk', and describes when cross-event mode is better than single-event.

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

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

Goes far beyond the readOnly/idempotent annotations: discloses caching (KV-level 1h), slippage assumptions (20-50bp, subtracted before ranking), Kelly capping at 0.25, placeholder-slug filtering, per-sport bias correction parameters, and diagnostic counters that explain empty segments. Also explains why partition arbs return parent-level kelly_fraction_half=0. No contradiction with annotations.

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

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

The description is long but information-dense and well-structured into labeled segments (model families, opportunity fields, tradeable-edge knobs, response top-level, diagnostics, caching). Every section earns its place given the tool's complexity (9 parameters, 3 model families). Slightly verbose but appropriately so for the scope.

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

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

With no output schema, the description compensates by outlining the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), key opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), and why segments may be empty. It covers the essentials for effective invocation, though exact nested field shapes (e.g., top_legs) are only hinted.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds crucial interaction context not in the schema: e.g., why min_kelly never filters partition arbs (because parent-level Kelly is 0 by design), the rationale for slippage defaults, and how min_liquidity/max_spread_pp act as 'tradeable-edge' gates. This elevates meaning beyond a mere schema restatement.

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 concrete verb+resource+objective: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the intended use case ('what should I bet on today') and differentiates from siblings like polymarket_arbitrage by covering three distinct model families and emphasizing discovery without paging hundreds of markets.

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

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

Provides strong contextual usage guidance: a clear 'built for' scenario, knob descriptions that shape when to use filters (tradeable-edge knobs), and a specific exclusion note about Fed candidates with rationale. It does not explicitly name sibling alternatives for when NOT to use this tool, but the context is sufficient to infer 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?

Exceeds the annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining what each field represents (e.g., 'trend (new | widening | stable | decaying)'), and disclosing limitations: 'history depth is bounded by the 60-day snapshot TTL', 'decay numbers come from daily closes of edge_pp_net... not intraday', and notes about snapshot gaps. This is rich behavioral context beyond read-only/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 long but well-structured with clear sections (Args, RESPONSE, LIMITS). It front-loads the core purpose and then details outputs and limitations. Every sentence contributes meaning, but the purpose phrase 'a fresh wide edge and a 3-week-old wide edge are different trades' is slightly verbose. Overall efficient 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?

Given no output schema, the description fully explains the response format (tracked, expired, snapshot_dates), field semantics, and limitations (TTL, daily closes). It covers prerequisites (snapshots from polymarket_edges), data gaps, and how to interpret results. This is comprehensive for a 2-parameter tool with no output schema.

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

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

Input schema covers 100% of the parameters with descriptions, so a baseline of 3 is appropriate. The description repeats parameter info ('Args: days (lookback, default 14, max 30), window (snapshot family, default "1wk")') but adds no new semantics beyond the schema. It aligns with the schema's 'clamp 2-30' and window enum values, so no gaps but also no added value.

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

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

The description opens with a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the question 'how long has this edge existed and is it shrinking?' differentiating it from sibling tools like polymarket_edges (current edges) by focusing on historical persistence and decay. The verb and resource are specific and unambiguous.

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

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

Provides clear context for when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades' — this implies using the tool to assess edge aging. However, it does not explicitly name alternatives or state when not to use, though the sibling context and phrasing imply it complements polymarket_edges. The guidance is sufficient but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral detail: it walks the order book ladder, computes slippage, identifies thin legs, and warns that partial basket fills convert an arb into unhedged directional risk. 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 and lengthy, but every sentence serves a purpose—mode details, parameter semantics, output fields, and explicit usage guidance. It is front-loaded with a clear purpose statement. However, it could be more scannable with bullets or shorter paragraphs for such a complex tool.

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

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

Given the tool's complexity, lack of output schema, and rich annotations, the description fully compensates by enumerating all return values (e.g., top_of_book, vwap_fill_price, capture_ratio), explaining mode-specific behavior, and covering edge cases like thin legs and forced directional risk. It leaves no critical gap.

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

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

While schema covers all four parameters, the description substantially enriches them—clarifying that only one of `market` or `event` is required, explaining `side` meanings per mode, and detailing how `size_usd` is interpreted differently (max spend, target proceeds, or settlement notional). This far exceeds schema descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource+scope that clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It also differentiates single-market vs basket modes, making its 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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and clearly defines when to use single-market vs basket mode. It names alternatives and gives concrete thresholds, leaving no ambiguity.

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

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

The description goes far beyond the annotations by revealing internal logic: compatibility_warning triggers in two specific cases, temporal_alignment determines whether spreads are valid, and skipped_cross_type/subtype counters explain dropped comparisons. It even gives concrete examples ('Kalshi range_bucket point-in-time vs Polymarket cumulative_threshold touch-anywhere — no arb exists'). This rich detail fully discloses the tool's behavior without contradicting the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence contributes substantive information about usage, response, or edge cases. It could be trimmed slightly, but the density and organization earn a high score.

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

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

With no output schema, the description fully explains the return structure: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers the complex logic of cross-venue comparison, including why spreads may be invalid, making the tool's behavior completely understandable. The safety and edge-case coverage is excellent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how parameters interact: topic auto-fetches, while kalshi_event_ticker and polymarket_event_slug override the mapped side. It also provides concrete examples ('KXFED-26OCT', 'fed-decision-in-june-825'), making parameter usage clearer than the minimal schema descriptions. This enhancement 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 specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's function and distinguishes it from sibling tools like polymarket_arbitrage. It further details two modes (topic shortcuts vs explicit tickers) that specify the exact scope of operation, leaving no ambiguity about what the tool does.

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

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

The description provides clear when-to-use guidance by explaining the two modes and how to choose between them: topic shortcuts for pre-mapped macro events and explicit tickers for custom pairings. It also warns about when not to use the tool: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable' and explains when spreads are meaningless (aligned:false). It stops short of naming alternative sibling tools explicitly, so it loses one point.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the dual behavior (retrieve vs. list), which goes beyond annotations. No contradiction.

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

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

The description is two sentences, front-loaded with the primary action, and every clause earns its place. It packs purpose, usage, scoping, and sibling relationships without 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?

For a simple tool with one optional parameter and no output schema, the description fully covers how to invoke it, what it returns (value or list), scoping, and related tools. There is no significant missing context.

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

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

Schema coverage is 100%, with 'key' described as 'Memory key to retrieve (omit to list all keys).' The description reinforces this and adds practical context by listing example memory contents (ticker, address, research notes) and explaining that the value was 'previously saved via remember.' This adds meaning beyond the raw schema, though the schema alone would have been adequate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes it from sibling tools like remember and forget, and even names them, 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 offers clear use-case context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions pairing with remember and forget. It lacks explicit when-not-to-use guidance, but the context is strong enough to guide 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?

Description claims mark_read:true mutates persisted feed state (flags events read), while annotation readOnlyHint=true declares the tool read-only. This is a direct contradiction, so score drops to 1 despite useful extra context on polling and HTTP endpoint.

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 dense sentences: main purpose, return payload, filtering options, mark_read behavior, and polling/alternative access. No redundancy.

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

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

With all params optional and no output schema, description fully covers what the tool returns (source, citation_uri, payload) and how to use it (filters, mark_read, polling). Also mentions alternative access for scripts.

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 all parameters are documented in schema. Description additionally gives an example type filter, clarifies since as ISO timestamp, and explains the side effect of mark_read, going beyond schema descriptions.

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

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

Uses specific verb 'Pull' and describes exact resource: fired events from subscription feed. Delineates content (source, citation_uri, raw event payload) and filter options, clearly distinguishing from sibling subscription management tools.

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

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

States polling is fine and points to an alternative HTTP endpoint, giving clear usage context. Doesn't explicitly state when not to use it, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond these hints: it fans out to SEC EDGAR, GDELT, GNews, and USPTO; explains the GDELT→GNews fallback on rate-limits/5xx; discloses the PatentsView API sunset causing soft-fail; and states it makes 'ONE parallel call' (performance behavior). This goes well beyond annotation basics.

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

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

The description is dense but every sentence earns its place: it starts with natural-language examples, explains sources and fallback behavior, covers `since` formats, summarizes the return shape, and gives an explicit pointer to the sibling tool. It is front-loaded with intent and avoids filler.

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

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

For a complex tool with multiple upstream APIs and fallback logic, the description is remarkably complete. It discloses the exact return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs), the behavior on rate limits/5xx, the USPTO soft-fail, and the alternative for static views. No output schema exists, but the description provides sufficient information to understand what will be returned.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly reiterates what the schema already says about `since` (ISO vs relative shorthand) and `value` (ticker/CIK). It adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') but does not introduce new semantic meaning for any 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 opens with multiple natural-language paraphrases ('What's new with X', 'latest on Y') and clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes itself from the sibling tool entity_profile ('Use entity_profile instead when you want the static profile'), demonstrating a specific verb+resource+scope with clear 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 gives explicit when-to-use context with concrete query examples and window options. It names the key alternative ('entity_profile') and explains why you'd choose that instead ('static profile... regardless of window'). It also describes the fallback behavior across data sources, providing clear guidance on what the tool is suited for.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds valuable context: 'key-value pair scoped by your identifier,' and persistence details for authenticated vs anonymous sessions. This exceeds the annotation baseline but stops short of describing overwrite behavior or error cases, which are minor for this tool.

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 core purpose. Each sentence adds meaningful information—usage scenarios, storage mechanism, retention policy, and companion tools. No filler or repetition, making it appropriately sized for the tool's simplicity.

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

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

For a simple write tool with 2 parameters and no output schema, the description covers all essential aspects: what it does, when to use it, persistence behavior, and integration with recall/forget. It is fully complete for its 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 covers 100% of parameters with clear descriptions and examples, so baseline is 3. The description reinforces the key-value concept but does not add syntax or format details beyond the schema. It adequately supports the agent without being redundant.

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: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') and resource ('data'), and distinguishes itself from siblings by referencing 'recall' and 'forget' as complementary operations. This makes the purpose unambiguous and distinct.

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 guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This goes beyond basic context and clearly directs the agent on when to invoke this tool versus related ones.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds meaningful behavior: graceful degradation when GLEIF/OpenFIGI unavailable, explicit `unresolved` field rather than omission, and multi-endpoint cascading. This exceeds 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?

Front-loaded with user-phrase examples and a clear `Use FIRST` directive. Some parenthetical detail is dense, but every sentence contributes context about sources, inputs, and fallback behavior.

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 multi-source resolver with no output schema, the description enumerates return identifiers (CIK, LEI, FIGI, RxCUI), source labeling, ownership chain, and unresolved handling. This gives the agent enough context 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?

Schema coverage is 100%, so baseline is 3. Description adds concrete examples for ticker/CIK/name and drug brand/generic, plus explains how each type is resolved. This provides 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?

Description opens with concrete examples and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings like entity_profile and compare_entities by identifying this as the identifier-lookup precursor.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and lists supported types with accepted input formats. It doesn't name alternative tools for exclusions, but the guidance is clear enough for a lookup 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 readOnly, openWorld, idempotent, non-destructive. Description adds that it makes multiple probes, ranks results, and returns score/confidence/signal density. This provides behavioral detail beyond the annotation flags.

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

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

Three sentences, front-loaded with the core function, each sentence adds useful context (purpose, use case, output). No redundancy.

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

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

Given the schema's detailed parameter descriptions and annotations, the description covers output format and use case sufficiently. No output schema exists, but the description explicitly lists the return fields (score, confidence, signal density), making the tool's behavior predictable.

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?

Input schema covers 100% of parameters with descriptions. The description adds the 'your brand + N competitors' interpretation and mentions the probing mechanism, but doesn't substantially extend parameter meaning beyond what's in schema. 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?

Description states verb 'Compare' and resource 'AI visibility across multiple entities', specifies it probes with ai_visibility_check, ranks by score, and identifies most/least recognized. This clearly distinguishes it from sibling ai_visibility_check (single-entity) and compare_entities (generic).

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

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

Description states usefulness for 'competitive AI-marketing audits' with an illustrative question. Implicitly contrasts with single-entity ai_visibility_check by saying 'across multiple entities side-by-side' and 'probes each entity'. Lacks explicit when-not-to-use or named alternatives, but context is clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses meaningful operational behavior: it fans out to two external services, returns a composite summary, degrades gracefully on partial failure, mentions the 5-30s potential delay, and explains that `sources_failed` will list timed-out sources. This is rich, honest 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 front-loaded with purpose and all sentences provide distinct value: usage, returned fields, ecosystem limitation, and failure behavior. It is longer than a minimal description, but the extra length is justified by the lack of an output schema and the need to explain the composite tool's edge cases.

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

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

Given that this tool has no output schema and is a composite across multiple services, the description is highly complete: it covers input scope, data sources, exact returned fields (summary block, per-advisory detail, links, alternative versions), and operational caveats like slow first measurement and graceful partial failure. An agent has enough to decide when to call it and how to interpret results.

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

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

Schema coverage is 100% and both `package` and `version` are already well-described in the schema. The description reinforces the npm scope and composite behavior but adds no substantive parameter-level details beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description opens with a concrete, specific purpose — a composite 'should I add this npm package' check — and names the exact data sources (deps.dev and bundlephobia). It also clearly scopes the tool to NPM, distinguishing it from generic dependency tools and any sibling candidates.

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?

Usage guidance is explicit: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion rule by stating NPM-only v1 and directing non-NPM ecosystems to deps.dev:version, so the agent knows when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context by explaining the matching fields (id, title, keywords, description) and the return structure (feature id, title, standards status). This goes beyond the annotations and gives the agent a clear picture of the search 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 front-loaded, with exactly two sentences that immediately identify the database ('caniuse') and the action ('find'). Every sentence earns its place: the first explains what it does, the second explains the return value and next steps. No wasted words.

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

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

Given that an output schema is present, the description does not need to explain return values in detail, but it still covers the key context: what database is used, how the search works, and what to do with the results. It lacks explicit edge-case handling (e.g., no matches, pagination), but for a search tool with a simple parameter set, it is reasonably complete.

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

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

The input schema documents 'limit' with a description ('1-50 (default 10)') but leaves 'query' undocumented. The description compensates by explaining that 'query' is a keyword to match against the database, and provides concrete examples ('webp', 'flexbox', 'CSS grid'). This adds meaning to the query parameter beyond the bare schema definition.

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

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

The description clearly states the tool's purpose: to find web platform feature IDs in the caniuse browser-compatibility database by matching a keyword against feature id, title, keywords, and description. It gives specific examples ('CSS grid, container queries, or WebP') and distinguishes this tool from siblings like feature and support by explaining that the returned ID should be fed to those tools.

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

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

The description provides a clear usage workflow: use this tool to find caniuse feature IDs, then feed the ID to 'feature' or 'support'. It implies when to use this tool versus those alternatives. However, it does not explicitly discuss when to use 'search_within' or other sibling search 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 mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond those by disclosing truncation at 200K chars with a flag, the BGE-base-en embedding model, cosine similarity over 500-char overlapping windows, and the return of offsets and similarity scores—all behavior not present in the annotations.

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

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

Three dense sentences front-load the core operation and value, then cover use case, pairing, mechanism, and limits. Every clause contributes information; there is no filler or repetition of the title.

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 still fully conveys the return shape (top-N passages with character offsets and similarity scores), the operational constraints (200K cap, truncation flag), the intended use case, and how the tool fits with a sibling tool. This is complete 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 coverage is 100%, so the schema already documents text, query, and limit with defaults and examples. The description adds meaning by framing text as 'the text you already pulled' and by noting the truncation/flag behavior for oversized inputs, which is a useful behavioral nuance not in the schema.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates from sibling tools by emphasizing that it operates on text already pulled (e.g., a SEC 10-K, an article) rather than performing a global search, and explicitly names ask_pipeworx_grounded as a related but distinct workflow.

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

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

It gives direct guidance: 'Use when the record is too big to cram into the prompt.' It also contrasts with ask_pipeworx_grounded by recommending a fetch-with-gateway then ground-over-relevant-passages pattern, and explains the benefit (saves context, verifiable offsets). This is explicit when-to-use and alternative-naming.

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

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

Beyond the annotations, the description discloses several important behaviors: it requires a Pipeworx OAuth account (anonymous/BYO cannot persist), SMS requires a verified phone with a 10/day cap, and webhook includes HMAC signing with a once-only secret and auto-disable after 10 failures. This adds substantial context about side effects and prerequisites.

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-organized, front-loading the purpose and then covering auth, types, and delivery options in a structured way. Every sentence adds value, though it is somewhat long; for the complexity it is appropriately concise.

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 explicitly states that it returns the subscription id and mentions webhook secret in the response. It covers all 5 subscription types, delivery channels, auth constraints, and rate limits, providing complete guidance for a 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?

Even though the input schema has 100% coverage, the description enriches parameter meaning with concrete examples for each subscription type (e.g., items:['5.02'] = officer change) and detailed delivery channel semantics (phone verification, HMAC signing, rate limits). This goes beyond the schema descriptions.

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

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

The description opens with a specific verb ('Create') and a clear resource ('proactive monitoring subscription to a live-data event stream'), which distinguishes it from sibling tools like list_subscriptions and recent_alerts. It also states the return value (subscription id), making the tool's purpose unambiguous.

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

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

The description clearly implies the tool is for proactive monitoring and mentions the always-on feed can be pulled via recent_alerts, providing an alternative for reading alerts. It does not explicitly contrast with other tools, but the context is sufficient for an agent to select this over list-only or search tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by explaining that results are 'drawn from the live catalog' and include 'exact tool + argument shape,' which enriches the behavioral model. It also clarifies the output structure (category buckets) without contradicting 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 a single dense paragraph, but it front-loads natural-language examples, then explains the return value, invocation options, and when to use it. Every sentence contributes specific information. While not as lean as a two-sentence example, it is well-organized and free of fluff, earning a 4.

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

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

Given no output schema and one optional parameter, the description fully addresses what an agent needs: the exact return structure (category-bucketed examples with tool and argument shapes), how to call with or without `topic`, and a strong 'use this FIRST' directive. It also enumerates the category buckets, making it complete for its scope.

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

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

The input schema already provides 100% coverage for the optional `topic` parameter, listing all valid values (finance, pharma, economics, etc.). The description adds a few extra examples ('betting') and says 'omit for a cross-category spread,' but this is essentially restating the schema. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering Pipeworx's capabilities, stating it 'returns category-bucketed example questions' with 'the exact tool + argument shape.' It distinguishes itself from other tools by saying 'Use this FIRST' and explicitly mentions meta-tools as a separate topic, showing specific verb + resource + 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?

The description explicitly states when to use: 'when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter for focusing. However, it does not name specific sibling tools it should be compared against or provide explicit when-not-to-use guidance, so it falls short of the strict 5-level.

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 that it returns both raw and parsed output, which is useful but doesn't disclose potential errors or rate limits. Given the strong annotation coverage, this is adequate but not exceptional.

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

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

The description is a single, focused sentence that front-loads the purpose and output. 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?

With a simple purpose, good annotations, and an output schema, the description is sufficient. It explains the return format and the input context without needing further elaboration.

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 three parameters are fully described in the schema with 100% coverage. The description does not add additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool checks whether a feature is supported in a given browser version, distinguishing it from sibling tools like `feature` and `search`. It specifies the output: raw caniuse string plus parsed verdict.

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

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

The description provides clear context for when to use this tool (checking browser support) via the direct phrasing. It does not explicitly mention alternatives or exclusions, but the 'Convenience' framing implies a quick check, and no sibling tool serves this exact purpose.

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

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

The description adds valuable behavioral context beyond annotations: ownership enforcement and the deactivation (not deletion) behavior. It explains the non-destructive nature, aligning with destructiveHint=false, and clarifies the effect on historical 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?

The description is three concise sentences, each covering a distinct aspect: the action, the ownership constraint, and the non-destructive nature. No redundant or excessive 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?

The description covers the core behavior and consequences for a simple unary tool. It does not describe the response format, but the pointer to recent_alerts provides verification context, and annotations cover idempotency. Slight gap remains around success/failure output, but overall it is complete enough.

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

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

The input schema already documents the id parameter with 100% coverage, including its source. The description only reiterates 'by id' without adding additional semantic meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource (subscription). It distinguishes from siblings like subscribe and list_subscriptions by the verb and scope. Ownership enforcement adds specificity.

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

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

The description provides clear context for when to use the tool (cancelling a subscription while preserving history) but does not explicitly name alternatives or exclusions. It implies the appropriate use case through the deactivation behavior and reference to recent_alerts.

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

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

The description goes well beyond the read-only/idempotent annotations by explaining the two processing paths (structured SEC EDGAR vs. grounded pipeline), the exact verdict values, and the critical distinction between could_not_verify (failure with verification_error) and unsupported (uncovered source). It also discloses that citations are returned via pipeworx:// and that the tool replaces sequential calls. This is rich 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?

Despite being long (~180 words), it is densely packed with information and front-loaded with trigger phrases. Every sentence earns its place: routing logic, return values, important caveats, and efficiency note. There is no filler or redundancy.

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

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

With no output schema, the description compensates by explaining the verdict types, the returned citation and reasoning, and the semantics of error cases (could_not_verify vs unsupported). It also covers parameter usage and two distinct claim types. Given the tool's complexity, this is complete enough for an agent to use correctly.

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

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

The schema already covers both parameters (claim, tolerance_pct) with descriptions, so baseline is 3. The description adds substantial value: concrete claim examples, explanation that tolerance_pct overrides implied tolerance, a usage hint for hallucination detection (set 1–2), and default behavior (implied by wording, capped at 5). This goes beyond the schema.

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

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

The description opens with explicit trigger phrases ("Is it true that…", "fact check", "verify the claim that…") and states its core function: "natural-language claim verification against authoritative sources." It clearly distinguishes itself from sibling search/ask tools by framing the output as a verdict (confirmed/refuted/etc.) rather than a search result, and even explains it replaces multi-step pipelines.

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 a clear usage context: "Use whenever the agent needs to check whether something a user said is factually correct." It also separates company-financial claims from other claims, indicating routing. However, it does not explicitly name alternatives or provide 'when not to use' guidance (e.g., when the user asks an open-ended question without a claim to verify).

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