Barcelona Events

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context: default model, scoring range (0-100), return structure (per-model fields + combined view), and API key behavior. No contradictions.

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

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

The description is two sentences plus a return format hint. It front-loads the core purpose, then adds model details and usage tips. No redundant 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?

Despite having no output schema, the description explains the return format sufficiently. It covers all parameters with clear examples and provides enough context for the tool's moderate complexity (4 params, 1 required).

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: explains default model pricing (free) and that Anthropic requires a BYO key with direct payment, and clarifies the 'context' parameter's role in disambiguation.

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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It uses specific verbs and resources, and the mention of 'AI-marketing audits, pre-launch brand checks, competitive monitoring' distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_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 explicit use cases (AI-marketing audits, brand checks, competitive monitoring) and explains when to use the optional Anthropic API key. However, it does not directly compare with siblings or state when not to use, leaving some 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?

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful context: the tool fills arguments, returns structured answers with citation URIs, and is a single fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but well-structured: it opens with the key usage directive, then explains mechanism, gives examples, and closes with alternatives. Each sentence earns its place, though it could be slightly more 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 the tool's complexity (general question-routing across thousands of sources) and lack of an output schema, the description is complete. It explains what the tool does, how it works, when to use it, what it returns, and how it compares to alternatives.

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

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

Schema coverage is 100% (all parameters are aliases for the same natural-language question), so baseline is 3. The description adds semantic guidance by providing example questions and explaining the type of input expected, which helps the agent formulate appropriate queries.

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

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

The description clearly states that ask_pipeworx routes user questions to 5,521 tools across 1,452 verified sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for 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?

The description explicitly says to prefer this tool over web search for authoritative data, provides concrete trigger phrases ("what is", "look up", "current"), and tells when to step up to ask_pipeworx_grounded or deep_research. It also notes it is the default entry point and works on every tier.

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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable context by stating that no candidate is currently active, so it currently matches ask_pipeworx exactly, and that it falls back to nothing—it is a full working router. This goes beyond the annotations by explaining the experimental nature and current behavior, though it could elaborate on what routing improvements entail.

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

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

The description is four sentences long, each providing necessary information: beta status, current state, usage guidance, and reassurance of full functionality. It is front-loaded with the key purpose and avoids verbosity, making it concise and well-structured.

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

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

Given the simple schema (one question field with aliases) and rich annotations, the description provides sufficient context for an agent to select and invoke the tool. It explains the tool's relationship to ask_pipeworx, its current behavior, and usage guidance. The lack of an output schema is mitigated by the statement that it has the same response shape as ask_pipeworx, though a brief note on what that response looks like would make it fully complete.

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

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

Schema coverage is 100% with all six parameters being aliases for the 'question' field, each clearly described in the schema. The description itself does not add parameter-specific meaning beyond saying 'same arguments,' but since the schema fully documents the parameters, 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 it is a beta version of ask_pipeworx, a universal router with the same 5,521 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and its experimental edge, making its 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?

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This provides clear when-to-use guidance and implies the alternative of using the stable ask_pipeworx, offering a strong usage guideline.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: it fetches data then extracts only from tool result, returns a structured object with evidence and refusal reasons (explicit enum), and discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but well-structured: purpose first, then mechanics, then use cases, then trade-off. It packs substantial detail (refusal reasons, return fields) into a single paragraph without redundancy. Slightly longer than necessary but each segment 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 no output schema, the description fully compensates by specifying the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal variants. It also covers the routing behavior, cost, and appropriate contexts, making it complete for a high-stakes tool.

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

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

Schema description coverage is 100%, with all parameters as aliases for 'question' and each is described. The tool description does not add parameter-specific meaning because none is needed beyond the schema. Baseline 3 is appropriate: schema does the heavy lifting.

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 'Hallucination-resistant answer mode for high-stakes reads,' immediately stating the specific verb, resource, and scope. It explicitly distinguishes from the sibling tool ask_pipeworx by noting 'Same routing as ask_pipeworx' but adds grounding/extraction, and the overall purpose is 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusions/alternative: 'prefer ask_pipeworx for casual lookups,' plus costs trade-off. This is model-level usage guidance.

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

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

The description discloses numerous behavioral traits beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, wide-spread warnings, and cancellation rule parsing. All annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and the description adds significant 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 excessively long (over 500 words) and includes many details that could be summarized or placed in a separate documentation. While well-structured with section headings, the verbosity reduces conciseness. It would benefit from being more compact while retaining critical guidance.

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

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

Given the tool's complexity (multiple input types, fan-out to many data sources, various response shapes, and edge cases like closed markets or wide spreads), the description covers all essential aspects: resolver contract, parent events, news fallback, low-confidence handling, and cancellation rules. It leaves no significant gaps for agents to guess behavior.

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

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

The input schema covers all three parameters with descriptions, and the description adds further nuance: examples for `market` (slug, URL, question text), explanation of `depth` ('quick' vs 'thorough'), and trade-offs for `include_raw`. The schema coverage is 100%, so the description enhances understanding rather than being essential.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), making the purpose unambiguous. The tool is distinct from siblings like `polymarket_edges` by focusing on one-shot research rather than edge tracking or arbitrage.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes extensive fan-out examples for different bet categories. However, it does not explicitly state when not to use the tool or mention alternatives, leaving some room for misuse.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds important behavioral details: for companies, it pulls latest 10-K financials with correct fiscal year handling; for drugs, it pulls FAERS adverse-event counts, FDA approvals, and trial counts. It also mentions result ordering by primary metric and return of citation URIs.

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 verbose but well-structured and front-loaded with trigger phrases. Every sentence adds value, though some details (e.g., fiscal year handling) could be integrated more concisely without losing informativeness.

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

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

Despite lacking an output schema, the description adequately explains what the tool returns (paired data with pipeworx:// URIs). It specifies result sorting behavior and covers both entity types comprehensively. Given the simplicity of the input schema, the description is complete and leaves no critical gaps.

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

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

Schema coverage is 100%, but the description adds meaningful context. For 'type', it explains the data sources for each enum value. For 'values', it provides examples and format constraints (tickers/CIKs for companies, drug names for drugs). This goes beyond the schema's minimal descriptions.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides trigger phrases ('Compare X and Y', 'X vs Y', etc.) and specifies the data sources for each type (SEC EDGAR for companies, FAERS for drugs). This differentiates it from sibling tools like entity_profile.

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 advises preferring this tool over sequential single-pack lookups when comparing entities. It also provides concrete trigger phrases that indicate when to use, effectively guiding the agent on appropriate usage scenarios versus alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the return packet with gaps[], the 'never invented' policy, the hop field and conditional citation_uri, contradictions[] on standard/thorough, and semantic excerpting of large records. It also reveals the account/payment requirement and latency ranges.

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 long paragraph, but it is front-loaded with the critical account requirement and logically flows through purpose, use cases, behaviors, and latency. Every sentence carries unique information, though bullet points would improve scannability; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully explains the findings packet (evidence, confidence, source, fetched_at, citations, gaps), the depth behaviors for gap recovery and contradiction scanning, limitations for current news, and performance expectations. It also covers account prerequisites, making it complete for a complex tool.

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

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

The schema already has 100% parameter description coverage, including the exact depth semantics and the paid nature of thorough. The description repeats these details without adding new parameter-level meaning, so it provides no extra value beyond the baseline.

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

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

The description explicitly states the tool performs 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources... in ONE call' and emphasizes it is 'NOT open-web search', clearly distinguishing it from siblings like ask_pipeworx. It also details the decomposition and parallel routing process, giving a 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 provides explicit guidance: 'Best for broad/multi-part questions over structured data', and explicitly contrasts with single-lookup and breaking-news use cases, naming ask_pipeworx as the alternative. It also instructs to use ask_pipeworx if not signed in and notes the payment requirement for thorough depth.

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, destructiveHint=false. The description adds that it returns '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 goes beyond annotations by describing the output format and readiness for use.

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

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

The description is somewhat long but well-structured: it lists many example tasks and provides a clear usage guideline. It earns its length by giving concrete context. Could be more concise, but effective.

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 6 parameters (1 required, 100% coverage) and no output schema, the description explains what the tool does, what it returns, and when to use it. It is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions aliases for query but that information is already in the schema parameter descriptions. It adds no new semantic meaning beyond what the schema provides.

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

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

The description uses specific verbs ('Find', 'browse, search, look up, or discover') and identifies the resource ('tools'). It lists many concrete use cases (SEC filings, FDA drugs, etc.) which clearly distinguishes it from sibling tools that operate on specific data types.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. Also implies alternatives: other tools are for specific tasks after discovery.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing safe read behavior. The description adds valuable context: it fans out across multiple sources in parallel, returns specific fields (cik, recent_filings, fundamentals, patents, news, LEI), and discloses that the patent source (USPTO PatentsView API) will sunset May 2025 and soft-fails. No contradictions with annotations.

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

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

The description is front-loaded with example queries, which is excellent for quick comprehension. It packs substantial detail into a coherent paragraph, but its length is justified by the tool's complexity. Every sentence adds value; there is no fluff. Slightly verbose but highly informative.

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

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

Given the tool has 2 parameters, no output schema, and moderate complexity, the description is remarkably complete. It explains what each data source provides (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists return fields with specifics (e.g., 'LATEST 10-K Revenues + NetIncomeLoss + Cash'), documents a known limitation (patent soft-fail), and clarifies input format. No gaps remain for effective usage.

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

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

Schema covers both parameters (type: company only, value: ticker or CIK) with descriptions. Baseline 3 due to 100% schema coverage. The description adds meaningful semantic value by reinforcing that names are not supported, explaining the zero-padded CIK format, and clarifying the type field limitation (only 'company' supported). This goes beyond what the schema alone provides.

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

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

The description specifies the tool's function with concrete examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and clearly states it returns a full cross-source profile of a US public company. It distinguishes itself from sibling tools like resolve_entity (handles names) and compare_entities, making its unique purpose 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 explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing clear when-to-use guidance. It also specifies input constraints (ticker or zero-padded CIK, not names) and directs users to resolve_entity first if they only have a name, giving clear when-not-to-use instructions.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable detail about return fields (venue, district, coordinates, dates) and content language (Catalan/Spanish), going 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?

Two efficiently crafted sentences: first defines purpose and filters, second specifies output content. 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?

No output schema, but description partially compensates by listing return fields. Missing details on pagination (offset) and potential response structure. Adequate but not fully complete.

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

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

Schema coverage is 100%, so each parameter is described. Description reinforces main filters but adds little beyond schema. Baseline 3 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?

Clearly states the tool finds upcoming cultural events in Barcelona with filtering by keyword, district, and date window. Distinguishes from siblings as no other tool handles this specific function.

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 on when to use (filtering events by keyword, district, date) but does not explicitly state when not to use or mention alternative tools. Sibling list shows no direct competitors, so implicit differentiation is adequate.

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. The description confirms deletion but adds no further behavioral context (e.g., reversibility, cascade effects). With annotations bearing the burden, a 3 is appropriate.

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

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

Two concise sentences: first clearly states purpose, second provides usage guidance. Each sentence is necessary 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?

For a simple tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing. No gaps remain.

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

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

Schema has 100% coverage with description 'Memory key to delete'. The tool description does not add any additional semantic details beyond the schema, so baseline 3.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes from siblings like 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', guiding context for alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds beyond this by detailing the exact process: fetching the page, extracting title/description/links, and emitting standard markdown. No contradictions.

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

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

Three sentences, each earning its place. The first sentence states the core action and purpose, the second describes the process, and the third lists use cases. No redundant or vague language.

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 2 parameters, no output schema, and comprehensive annotations, the description fully explains input, process, and output (single text blob). It 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?

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining how the parameters are used in the generation process (e.g., fetches the page, extracts key elements). This exceeds the baseline of 3 for high 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 explicitly states it generates an llms.txt file for any URL, with specific actions like fetching, extracting, and emitting markdown. The verb 'generate' pairs clearly with the resource 'llms.txt file', and the tool is distinct from the unrelated 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?

The description provides explicit use cases: getting a client's site indexed, drafting your own project's llms.txt, or auditing competitor AI visibility. While it doesn't list when not to use, the sibling tools are unrelated, so no ambiguity arises.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds return field details, providing context beyond annotations without contradiction.

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

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

Two sentences, front-loaded with purpose and return fields, no wasted words.

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

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

For a simple tool with one optional parameter, good annotations, and no output schema, description fully covers what the agent needs to invoke correctly.

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

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

Schema covers the one parameter fully (100% coverage). Description does not add parameter-specific info, but 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?

Clearly states verb 'List', resource 'subscriptions', and specifies returned fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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: 'to review what you're monitoring before adding more or to find an id to cancel'. Lacks explicit exclusions but sufficient for a simple list 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?

Although annotations signal readOnlyHint=false, the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free and not counted against quota, returns a claim_token when no account is used, and the team reads digests daily. 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?

Despite being long, it is dense and front-loaded: purpose in first sentence, followed by clear usage conditions, exclusions, mechanics, and limits. Every sentence adds operational guidance (don't paste end-user prompt, naming convention, daily digest). No 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?

With no output schema, the description explains return behavior (claim_token on anonymous filing; later retrieval of status and changes). It also covers prerequisites, exclusion criteria, and rate limiting, making it fully self-contained for a feedback 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 describes all four parameters with 100% coverage, so baseline is 3. Description adds value for claim_token (pass it back later with no other args) and context (structured reference to pack/tool/vertical), plus message guidance (1-2 sentences typical). Slightly above baseline but not necessary to compensate for schema gaps.

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 a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from siblings like ask_pipeworx and discover_tools by scoping to Pipeworx-owned tools and explicitly excluding other MCP servers.

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 mapping: bug for wrong/stale data, feature for missing tools, data_gap for unavailable data, praise for good experiences. Includes a strong exclusion — do not report issues for non-Pipeworx MCP servers — and gives a fallback ('file it with that server instead'). Also explains the claim_token workflow and daily rate limit.

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. Description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions.

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

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

Concise: one sentence summary, followed by bullet-like use cases, then additional details. Every sentence adds value with no redundancy.

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

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

Given no output schema, description hints at return shape (top tools, top packs, total call volume). Covers caching and data origins. Sufficient for a simple read tool with one optional parameter.

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

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

Schema coverage is 100% for the single parameter. Description adds meaning by explaining the trade-off between short and long windows ('surface what's hot right now' vs 'show steady-state demand'), going beyond raw enum values.

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

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

Description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource ('top tools, top packs, total call volume'), and distinguishes from siblings like 'discover_tools' by focusing on trending data.

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

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

Explicitly lists three use cases and explains the difference between window sizes. Lacks explicit when-not-to-use or alternatives, but for a simple read tool, the use cases are clear enough.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate a safe read operation. The description adds significant behavioral context: walks child markets, checks date-axis/threshold-axis ordering, partition sum should ≈1, deviations >3pp emit signal, semantic anchor with Jaccard similarity, partition filter for placeholders, and fill check against live CLOB depth. 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 information-dense and well-structured: first sentence states purpose, then each mode is explained, followed by sub-features (semantic anchor, partition filter, fill check). It is not overly concise but every sentence adds value, making it appropriate for the complexity without being 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 moderate complexity (2 optional params, no output schema), the description thoroughly covers all aspects: purpose, argument modes with examples, algorithmic details (Jaccard similarity, placeholder filter, fill check), and return structure (opportunities[], partition_check, fill_check). It also references a sibling tool for custom sizing, making it self-contained.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description adds value beyond the schema by explaining why to use each mode, providing example slugs, and detailing the algorithmic behavior (e.g., partition_check, semantic anchor, fill check). This justifies a score above the baseline of 3.

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

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

The description starts with a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges, polymarket_edge_tracker, polymarket_fill_risk, and polymarket_kalshi_spread by focusing on arbitrage detection with unique methods.

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

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

The description provides explicit guidance on when to use each of the three modes (no args, event, topic) with examples and explains the limitations (e.g., Jaccard similarity threshold, placeholder filter). It does not explicitly state when not to use the tool, but the clarity of the modes and references to polymarket_fill_risk for custom sizing suffices.

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

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

The description goes far beyond annotations, detailing model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching (1h at KV level), edge calculation (edge_pp_net, kelly_fraction), tradeable-edge knobs (min_liquidity, max_spread_pp), and response structure with diagnostics. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is long but well-structured, starting with a clear purpose, then detailing segments, edge components, knobs, and response format. It is front-loaded with the core action and uses clear separators. Could be slightly more concise, but the detail is warranted for the 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 the tool's complexity (9 parameters, no output schema, but detailed response description), the description is highly complete. It explains the response structure (by_segment, fed_candidates, diagnostics), caveats (Fed data unreliability), and all knobs. Annotations cover safety. No gaps identified.

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 schema descriptions are detailed. The description adds value by explaining how tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) affect behavior and filtering, providing context beyond the schema definitions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes itself from siblings like polymarket_arbitrage by focusing on discrepancies with Pipeworx data.

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

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

The description explicitly states it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides context for each segment and explains why certain segments might be empty via diagnostics. However, it does not explicitly compare with alternatives like polymarket_arbitrage or specify when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: data source (daily snapshots), history bounds (60-day TTL), decay calculation method, and response structure details.

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

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

The description is detailed but well-structured: starts with core purpose, then explains args, then response fields, then limits. Every sentence adds value; though long, it is necessary given no output schema.

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

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

For a tool with no output schema, the description thoroughly explains the three response sections (tracked, expired, snapshot_dates) and their fields, along with limits and data source nuances. It is complete for an agent to understand invocation and output.

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 with descriptions, but the description adds defaults and constraints clarifications (e.g., days default 14 max 30, window default '1wk') and explains the meaning of the output structure, going beyond schema alone.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question. It distinguishes itself from the sibling 'polymarket_edges' by being a derived analysis tool.

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

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

The description implies usage for tracking edge persistence but does not explicitly state when to use this tool versus alternatives like 'polymarket_edges' or 'polymarket_arbitrage'. No when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds rich behavioral details: walking the ladder, returning specific fields, explaining basket mode risks, and alerting about forced 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?

While dense and informative, the description is a single paragraph that could benefit from bullet points or clearer section breaks. However, every sentence earns its place and it's front-loaded with the core purpose. Efficient given the complexity.

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

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

Despite no output schema, the description thoroughly lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It explains the dominant loss mode (partial fills). Missing error conditions or input validation details, but acceptable for a check tool.

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

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

Schema coverage is 100% with property descriptions, but the tool description adds valuable context beyond schema: explains default behavior for basket side ('auto from partition sum'), clarifies size_usd interpretation (max spend vs target proceeds), and provides constraints (clamp 10–1,000,000).

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with two distinct modes (single-market and basket). It differentiates from siblings by explicitly telling the agent to use this tool before acting on 'polymarket_arbitrage' or 'polymarket_edges' signals.

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 ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and why (partial basket fills convert arb into unhedged directional position). Also specifies required parameters for each mode.

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 annotations (readOnlyHint, idempotentHint), the description details all output fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains their meaning, including edge cases like temporal misalignment. No contradiction with annotations.

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

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

The description is long but well-organized: definition, modes, response details, safety fields. It front-loads the core purpose and uses clear headings. Every sentence adds necessary information for a complex tool.

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

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

Given no output schema, 3 parameters (all covered), and rich annotations, the description fully explains inputs, outputs, edge cases, and safety fields. An agent can confidently invoke and interpret results.

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

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

Schema covers 100% of parameters. The description adds significant value by explaining the two modes, how topic overrides work, and that explicit parameters override topic-mapped sides. 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 clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two distinct modes (topic shortcuts and explicit pairing). This distinguishes it from siblings like polymarket_arbitrage, which focus on intra-venue arbitrage.

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

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

The description explicitly explains the two modes and when each is appropriate, including a warning that pre-mapped topics often yield compatibility_warnings. It does not explicitly list alternative tools but provides enough context for an agent to decide when to use this tool over others.

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 behavioral traits beyond annotations: scoping to an identifier and the pairing with remember/forget. Annotations already indicate read-only, idempotent, and non-destructive, so the description adds useful context without contradiction.

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

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

The description is concise, with only 4-5 sentences, and front-loads the primary action. Every sentence adds value, and no fluff or repetition is present.

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 adequately explains the return behavior (value or list of keys) and provides sufficient context for use. It is considered complete for this simple tool.

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

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

Schema coverage is 100% and the schema description already explains the key parameter (omit to list all keys). The tool description adds some context about scoping but does not significantly 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 tool's purpose: retrieve a saved value or list all keys. It uses specific verbs ('Retrieve', 'list') and distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description explains when to use this tool (to look up context saved earlier) and pairs it with 'remember' and 'forget'. While it does not explicitly state when not to use it, the guidance is clear and includes context about scoping.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: setting mark_read:true flags events as read, affecting subsequent calls. It also mentions the alternative HTTP endpoint. This goes beyond annotations without contradicting them.

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

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

The description is a single paragraph but is well-structured: it starts with the core action, then details return fields, filtering, mark_read behavior, and an alternative access method. Every sentence provides useful information without redundancy.

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

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

Although there is no output schema, the description explains what is returned (source, citation_uri, raw payload). It covers all parameters and gives practical usage hints. For a query tool with good annotations, this is sufficient context for agent selection and invocation.

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

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

All 5 parameters have descriptions in the schema (100% coverage). The description adds extra context: explains that 'since' expects ISO timestamp, and 'mark_read' flags events as read to influence future calls. This adds meaningful behavior beyond the schema descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself by focusing on alert events from the subscription feed, but does not explicitly differentiate from similar sibling tools like 'events'.

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

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

The description provides usage guidance: it mentions that polling works fine and points to an alternative URL for scripts/dashboards. It explains filtering options (type, since) and the mark_read behavior, but does not explicitly say 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, etc. The description goes beyond by detailing the fan-out to specific data sources, fallback logic (GDELT to GNews on rate limits/5xx), soft-failure of USPTO due to API sunset, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is information-dense yet well-organized. It opens with query examples, then explains data sources and fallback, parameter details, return format, and comparison with a sibling tool. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, API sunset, no output schema), the description covers all necessary aspects: what it does, how it handles failures, parameter formats, return structure, and when to use an alternative. No gaps remain.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds significant meaning: for 'since' it explains ISO date vs. relative shorthand with examples, for 'value' it specifies ticker or CIK, and for 'type' it notes only 'company' is supported. This enhances 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 tool provides a change feed for a company over a time window, fanning out to multiple sources (SEC, GDELT, GNews, USPTO). It explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use that instead, meeting the high bar of specificity and 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 examples of queries and provides clear context for when to use this tool ('What's new with X') vs. alternatives ('Use entity_profile instead'). It also offers parameter guidance (e.g., 'Use "30d" or "1m" for typical monitoring') and explains fallback behavior.

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

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

While annotations already indicate idempotentHint=true and destructiveHint=false, the description adds valuable context: scope by identifier, persistence differences between authenticated and anonymous sessions, and that it's a write operation. No contradictions.

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

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

The description is moderately sized (three sentences) and front-loaded with purpose. Each sentence adds distinct information. Could be slightly more concise, but the structure is logical 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?

For a simple write tool with two parameters and no output schema, the description covers purpose, usage, behavior, scoping, and persistence. It mentions pairing with recall but doesn't detail retrieval behavior; however, overall it is sufficiently complete for an agent to use 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% with both parameters described adequately. The description adds semantic value by providing example keys like 'subject_property' and explaining that value is 'any text', which helps an agent choose appropriate values 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 purpose: 'Save data the agent will need to reuse later' and specifies the resource as key-value pairs. It distinguishes from siblings by naming recall and forget, and provides concrete examples of usage (ticker, address, preference).

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

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

Explicitly says 'Use when you discover something worth carrying forward' and gives examples. It also instructs to pair with recall and forget, providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it mentions internal cascading through lookup endpoints, auto-disambiguation, and citation URIs in the return payload. This enriches the agent's mental model without contradicting annotations.

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

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

The description is dense but well-structured with a clear directive, supported types, and return details. It uses a 'SUPPORTED TYPES' section to organize information efficiently. While slightly long, every sentence adds value and it is front-loaded with the purpose and usage directive.

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

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

Given there is no output schema, the description must convey return values and behavior, and it does so thoroughly. It specifies exactly what each entity type returns (company: ticker + CIK + company_name + citation URI; drug: RxCUI + ingredient + brand + citation), and explains the internal cascade. This is complete 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?

The schema already covers both parameters 100%, so the baseline is 3. However, the description adds meaningful examples and clarifies accepted input forms for the value parameter (ticker, CIK, or name for company; brand or generic for drug), plus the 'auto-disambiguated' behavior, which goes beyond the schema's basic descriptions.

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

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

The description opens with example queries and then explicitly states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This is a specific verb+resource combination and clearly differentiates from sibling tools by positioning itself as the primary name-to-ID resolver.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types (company, drug) with accepted input formats and notes that it replaces 2-3 manual lookups, giving clear context for when to invoke this tool versus alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds how it probes each entity internally and returns ranked list with score, confidence, signal density. 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?

Three sentences, front-loaded with purpose. Each sentence adds value: what it does, how it works, use case/output. No waste.

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

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

Despite no output schema, description fully specifies input (2-8 entities), process (probe and rank), and output (ranked list with score, confidence, signal density). Annotations cover safety. Complete for this tool.

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

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

Schema covers 100% of parameters. Description adds key semantics: first entity is 'subject', rest are competitors; 'models' default to workers-ai; 'context' disambiguates common names. Adds meaning beyond schema.

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

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

Description clearly states verb 'compare', resource 'AI visibility', and action 'probes each entity with ai_visibility_check, ranks by score'. Distinguishes from sibling 'ai_visibility_check' (single entity) and 'compare_entities' by focusing on AI 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?

Explicitly states usage context: 'useful for competitive AI-marketing audits' and provides a concrete question. But does not explicitly state when not to use or mention alternatives.

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

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

Adds details about partial failures (bundlephobia timeout), graceful degradation, and 'sources_failed' list. Mentions first measurement can take 5-30s, which complements readOnlyHint, openWorldHint, idempotentHint annotations without contradiction.

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

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

Densely packed but front-loaded with core purpose. Every sentence adds value; however, could be slightly trimmed without losing information.

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

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

Despite no output schema, description details return format (summary block fields, per-advisory detail, links, alternative versions) and handles partial failures. Comprehensive for a complex tool with multiple data sources.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by noting scoped packages accepted for 'package' and 'version' defaults to latest. Provides incremental guidance beyond schema.

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

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

The description clearly states it's a composite check for 'should I add this npm package', covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by specifying NPM scope and referencing deps.dev:version for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also notes NPM only in v1 and directs other ecosystems to deps.dev:version directly.

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, openWorldHint=true, and destructiveHint=false. Description adds specific behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. No contradictions.

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

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

Concise at 4 sentences, front-loaded with the core purpose. Every sentence adds essential information—usage guidance, behavioral details, and technical specifics. No redundant or vague statements.

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 clearly states the return format (passages with character offsets and similarity scores). Covers usage, limitations, and pairing with sibling tools. All necessary information for an agent to correctly select and invoke the tool is present.

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

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

Schema description coverage is 100% with detailed descriptions for all three parameters. Description adds extra context: examples for query, default and range for limit, and explanation of text as fetched record. This significantly enriches the schema information.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs and examples. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded, making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also provides guidance on pairing with ask_pipeworx_grounded, and explains benefits like saving context and returning only relevant passages.

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 implies each call creates a new subscription with a new id, contradicting the idempotentHint annotation (which suggests repeated identical calls yield the same result). This is a serious contradiction. The description does add value beyond annotations (prerequisites, delivery limits, webhook auto-disable), but the contradiction dominates.

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

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

The description is detailed but well-structured, starting with core purpose, then listing types and delivery options with examples. Every sentence adds value, though it could be slightly trimmed without losing clarity.

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

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

Given the complexity (3 params, nested objects, 5 enum types, optional delivery, no output schema), the description covers all necessary aspects: types, params, delivery options, prerequisites, limits, and return value (subscription id). It is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by explaining each type's params structure with examples, delivery channel options, and constraints (e.g., series_id for fred_series, phone verification). This enriches understanding beyond the schema.

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

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

The description clearly states the verb 'Create' and resource 'proactive monitoring subscription to a live-data event stream', and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Explicitly says when to use (create subscription), prerequisites (Pipeworx OAuth account, phone verification for SMS), and provides examples for each type. Implicitly guides away from alternatives like list_subscriptions (for listing) or recent_alerts (for pulling).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: returns example questions with tool+argument shapes, drawn from live catalog, and behavior with/without argument. No contradictions.

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

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

Front-loaded with natural language phrases, structured with parenthetical details. Slightly long but every sentence adds value. Could be slightly more concise, but overall 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?

Complete for a simple tool with one optional param. Explains purpose, usage, behavior with/without argument, and output nature (category-bucketed questions). No output schema needed as description covers it.

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

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

One parameter (topic) with 100% schema coverage. Description adds meaning: lists focus areas (finance, pharma, etc.) and explains omitting gives full spread. Adds value beyond schema.

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

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

Description clearly states the tool returns category-bucketed example questions for onboarding, using verbs like 'returns' and specifying the resource (Pipeworq capabilities). It distinguishes itself from siblings by being the first tool to use when unsure.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus with a topic. Does not state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description adds value by specifying the deactivation behavior (not deletion). However, it could mention idempotency or permissions beyond ownership. The annotations already cover the safety profile well, so a 4 is appropriate.

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

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

Two concise sentences deliver all necessary information without redundancy. Front-loaded with the core action, followed by crucial constraints.

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 no output schema, the description fully covers behavior (ownership, deactivation), outcome (historical events preserved), and references to related tools. No gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents the 'id' parameter. The description adds minor context ('returned by subscribe') but does not provide additional semantic value beyond what the schema provides. Baseline 3 is warranted.

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

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

The description uses a specific verb ('Cancel') and identifies the resource ('subscription by id'). It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by stating the action and ownership enforcement.

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

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

Explicitly states when to use the tool ('Cancel a subscription') and what not to expect ('not deleted'). Provides key context: ownership enforcement and deactivation behavior with reference to history via '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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral detail: two processing paths (SEC vs. grounded), tolerance override, return components (verdict, value+citation, reasoning), and efficiency gains (replaces 4-6 calls). No contradictions.

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

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

Single dense paragraph, but every sentence adds value. Could be slightly improved with bullet points or clearer separation of path descriptions, but overall efficient and front-loaded with purpose.

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

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

Given no output schema, the description fully explains the return structure (verdict, value with citation, reasoning). It covers inputs, processing, and outputs completely for a verification 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?

Parameter schema has 100% description coverage with examples and default behavior. Description adds context: claim examples and tolerance_pct override semantics. The description enriches the schema without redundancy.

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

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

Description uses multiple trigger phrases ('fact check', 'verify the claim') and clearly states the tool's purpose: natural-language claim verification. It distinguishes between financial claims (SEC path) and other claims (grounded pipeline), and lists sibling tools none of which are claim-verification, making its uniqueness clear.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' Also provides context on specialized handling for financial vs. other claims. No explicit when-not-to-use, but the description is sufficiently clear about its domain.

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